Bookbinder

Ebook format conversion.

Basic use

Display the contents of an EPUB as a JSON "map":

$ bookbinder map path/to/file.epub

Convert an EPUB to an Openbook directory (the directory need not exist yet):

$ bookbinder convert path/to/file.epub path/to/dir

Convert an EPUB to an Openbook archive:

$ bookbinder convert path/to/file.epub path/to/file.openbook

Convert an Openbook to an EPUB (...is not yet fully implemented!)

Use as a Ruby library

EPUB to Openbook:

require 'bookbinder'
epub = Bookbinder::Package::EPUB.read('book.epub')
openbook = epub.export(Bookbinder::Package::Openbook)
openbook.write('book.openbook')

For other basic actions, take a look at lib/bookbinder/operations.rb. This class provides a basic layer of convenience, such as reducing the above to:

require 'bookbinder'
Bookbinder::Operations.convert('book.epub', 'book.openbook')

Improving Bookbinder

Inside Bookbinder, a "book" is simply a nested hash of properties and values. This hash is called "the map". Properties of the map that are transferrable between ebook package formats should follow the Openbook convention, which is currently maintained here:

https://gist.github.com/joseph/7303930

The key to Bookbinder is this: for every feature of an ebook format, we create a "transform" class that does two things:

  • parses the raw config from the package into standard Openbook properties on the map; and
  • generates raw config into the package from those same standard Openbook properties on the map

Basically, for every feature, the transform class describes how to read it, and how to write it.

The nice thing about this set-up is that if multiple package formats support the same feature, their transform classes work on the same map. Say you are converting from EPUB3 to Openbook - the book's title is parsed out of the EPUB file into the map using the transform at lib/bookbinder/transform/epub/title.rb. Then the map is handed over to the Openbook package, and the transform at lib/bookbinder/transform/openbook/title.rb would write it out to the new package file.

You can of course convert a package to its own format: in this case the same transform class does both the reading and the writing out -- the effect of this is to "tidy" the package.

To add a package format Bookbinder, you should create the package class in lib/bookbinder/package, then create directory of transforms in lib/bookbinder/transform. You can borrow transforms from other packages. For instance, it might make sense for a DAISY package to share some of the transforms in EPUB, or for a hPub package to borrow some transforms from Openbook.

If you are adding a new feature to Bookbinder, you create the appropriate transform class for each package that supports the feature, and then add the equivalent tests.

Planned format support

  • Openbook
  • EPUB3
  • EPUB2
  • hPub
  • PDF
  • ...

Attribution and licensing

Bookbinder was originally developed at OverDrive, Inc. Released under the MIT License. See MIT-LICENSE in this directory.