Package and check your EPUB
By this point, you should have an EPUB bundle ready to package. This bundle will either be a new book that you created yourself or one that uses the raw files available from Downloads.
The OEBPS Container Format portion of the EPUB specification has several things to say about EPUB and ZIP, but the most important are:
- The first file in the archive must be the mimetype file (see Mimetype in this tutorial). The mimetype file must not be compressed. This allows non-ZIP utilities to uncover the mimetype by reading the raw bytes starting from position 30 in the EPUB bundle.
- The ZIP archive cannot be encrypted. EPUB supports encryption but not at the level of the ZIP file.
Using ZIP version 2.3 under a UNIX®-like operating system, create the EPUB ZIP file in two commands, as in Listing 11. (These commands assume that your current working directory is your EPUB project.)
Listing 11. Bundling the EPUB into a valid epub+zip file
$ zip -0Xq my-book.epub mimetype $ zip -Xr9Dq my-book.epub *
In the first command, you create the new ZIP archive and add the mimetype file
with no compression. In the second, you add the remaining items. The flags
extraneous information in the .zip file;
recursively include the contents of META-INF and OEBPS directories.
Although the EPUB standard isn't especially difficult, its XML files must be validated against specific schemas. If you use a schema-aware XML editor to generate the metadata and XHTML, you're over halfway there. Make a final check with the EpubCheck package (see Resources).
Adobe maintains the EpubCheck package, and it's available as open source under the Berkeley Software Distribution (BSD) license. It is a Java program that can be run as a stand-alone tool or as a Web application, or you can integrate it into an application running under the Java Runtime Environment (JRE) version 1.5 or later.
Running it from the command line is simple. Listing 12 provides an example.
Listing 12. Running the EpubCheck utility
$ java -jar /path/to/epubcheck.jar my-book.epub
If you failed to create some of the auxiliary files or introduced an error into the metadata files, you might get an error message like that in Listing 13.
Listing 13. Sample errors from EpubCheck
my-book.epub: image file OEBPS/images/cover.png is missing my-book.epub: resource OEBPS/stylesheet.css is missing my-book.epub/OEBPS/title.html(7): 'OEBPS/images/cover.png': referenced resource missing in the package Check finished with warnings or errors!
You might need to set your CLASSPATH here to point to the location of the EpubCheck installation, as it does have some external libraries to import. You probably need to set the CLASSPATH if you get a message like:
org.xml.sax.SAXParseException: no implementation available for schema language with namespace URI "http://www.ascc.net/xml/schematron"
If the validation was successful, you'll see "No errors or warnings detected." In that case, congratulations on producing your first EPUB!
Testing isn't just about validation: It's also about making sure the book looks right. Do the stylesheets work properly? Are the sections actually in the correct logical order? Does the book include all the expected content?
Several EPUB readers are available that you can use for testing. Figure 1 shows a screen capture from Adobe Digital Editions (ADE), the most commonly used EPUB reader.
Figure 1. The EPUB in ADE
Your font colors and images are appearing, which is good. ADE is not correctly rendering the title in a sans-serif font, though, which might be a problem with the CSS. It's useful here to check in another reader. Figure 2 shows the same book rendered in my open source, Web-based EPUB reader, Bookworm.
Figure 2. The EPUB in Bookworm
In this case, it's just that ADE doesn't support that particular declaration. Knowledge of the quirks in individual reading software will be essential if exact formatting is important in your digital book.
Now that you've done the laborious process of creating a simple EPUB from scratch, see what it takes to convert DocBook, a common XML documentation schema, into EPUB.