epubcheck 102: Running epubcheck
In part one of this series, we looked at why epubcheck is an important tool in any ebook maker’s toolchest. Today we look at how to use it.
OK, now that we know why to use epubcheck, let’s look at how. There are a couple ways to use epubcheck in your workflow, ranging from super easy to “yes. use the terminal” (which for some of us is also super easy 🙂 )
Online Tool
A very simple way to do one-off checks is to use the online validator created by the IDPF. Just upload your EPUB file and press the “validate” button. There are a few downsides to this version. First, it only accepts files up to 10MB. For most ebooks that’s probably fine, but for books with videos or lots of images you’ll need to look at a different solution. Secondly, this can be a tedious process if you need to check the file, then edit it, then re-check it. A rinse and repeat process might not be ideal with this tool.
Flight Deck
As I’ve previously mentioned, Flight Deck is one of my favorite ebook validation tools. It has epubcheck built into its validation process. There’s a few advantages to using flight deck over the simple IDPF tool. First, it supports a larger maximum upload file size. It also offers additional validation services that are either required or recommended by ebook retailers.
There’s another benefit that isn’t as black and white worth discussing. As we’ll talk about in the next installment of this series, epubcheck’s error reporting can be a bit vague at times. The language its uses can be difficult to parse, and trying to solve some of the more abstract error messages can be a pain. Flight Deck tries to help by re-writing some of the error messages to be a little more human-friendly.
Like the IDPF tool, it may also not be great if you go through a lot of rinse and repeat to solve errors.
Pagina
More than a few ebook creators I know swear by Pagina. It’s a desktop tool, and it has the added benefit of zipping up your unzipped EPUB file. This makes it much more useful in most people’s rinse and repeat workflows. It also offers translations of errors to other languages if you’d prefer something other than English.
(thanks to India Amos for reminding me of this great tool.)
Terminal Usage
I know, I know. The Terminal is scaaaaaary. So if it’s not your cup of tea, skip this part. If you do like to use the terminal or are considering building epubcheck into a more complicated workflow, read along.
Download the latest release from Github
All of epubcheck’s releases are available on Github here. Unless you know you want a beta release, I recommend downloading the “Latest Release” (as of this post that is 3.0.1).
Run the application
Once downloaded, running the script is as simple as running the following command in terminal
java -jar path/to/epubcheck-x.x.x.jar path/to/file.epub
where epubcheck-x.x.x.jar is the name of the file you downloaded. (as of this post’s writing it would be epubcheck-3.0.1.jar)
In the next part of the series we’ll look at some of the error messages you get from epubcheck and ways to fix your file.
You did not mention one detail: when using epubcheck, wrap the path of the EPUB file in quotes in order for epubcheck to not balk when the path contains spaces.
Another thing to consider is that you will rarely run epubcheck once per book because the first time you so it will most probably report that your EPUB does have errors (specially if you hand-crafted or tweaked it yourself). Instead, it will usually be something more like this:
1. Run epubcheck.
2. Rinse.
3. Repeat until the water comes out clean.
Because of that, running epubcheck in the Terminal is handy since it allows you to check the EPUB folder containing the files that you will finally be zipping up into en .epub file, before you actually zip them all up.
You can run epubcheck to check an EPUB folder like this:
java -jar path/to/epubcheck-x.x.x.jar -mode exp "absolute/path/to/epub_directory"Note, by the way, that epubcheck is also available from the Homebrew package manager for Mac OS X, so if you install epubcheck using that instead of downloading it from Github, you can type:
epubcheckwhere in this article says:
java -jar path/to/epubcheck-x.x.x.jarSo, in order to check a folder:
epubcheck -mode exp "absolute/path/to/epub/directory"The path of the EPUB folder must be absolute, not relative (past versions of epubcheck did allow relative paths, but not the latest [boooh!]). You could also run it like this:
cd "path/to/epub_directory"epubcheck -mode exp "$PWD"If you provide the
-saveoption, it will even provide you the final zipped up .epub file if no errors come out.epubcheck -mode exp -save "absolute/path/to/epub/directory"Adopting the practice of using epubcheck as the only means of producing the final .epub file like this instead of any other zipper or script is nice, since this way you can be sure that no .epub you ship ever will have any epubcheck errors.
If the command line is scary, Pagina’s EPUB-Checker also allow you to check the EPUB folder instead of the final EPUB file too, and it will too zip it up into an .epub file if no errors are reported.
[…] Part 1 we looked at why Epubcheck is important. In Part 2 we looked at the various ways to use it. Here in Part 3 we’ll look at how to interpret the error […]
Pagina seems to be a simple GUI for running epubcheck (besides its EPUB packer capabilities), the translations of error messages are provided by epubcheck itself.
It’s not “besides”: Pagina is but a frontend to epubcheck, both for validation and packaging. It’s epubcheck too the one packaging the EPUB, as per the
-saveargument described in my comment above.Oh, interesting, I didn’t know that! I just assumed that the “Do One Thing and Do It Well” UNIX paradigm would be in place… and I didn’t read your previous comment because running epubcheck wasn’t an issue for me. In my opinion, there shouldn’t be any EPUB packers where the result is allowed to be an invalid one.
This helpful help and advice means a whole lot to someone like me and a whole lot more to my friends.