State of the Union: A Very Basic Ruby Epub Library

Currently I enjoy, through hacks and such, easy ways to create an ePub project directory, update the OPF and NCX files within, compile it all, and even run epubcheck, all very easily.

I’m starting to refactor and redesign all that, with an eye to providing a Ruby library that allows manipulation of various parts of Epub, as well as a Project class tying the elements together (after all, when a unique identifier needs to be synced between two files with different formats of almost entirely different inheritances, it gets a bit annoying to do manually).

One day I’ll probably stick this all in a RubyCocoa interface, so that we have an opposite number to the Windows-only Mobipocket tools.

This library will one day, given the blessings of the RubyForge administrators, become a gem for people to play with. Right now it resides over at, where you can see a roadmap and browse the code and check-ins.

The state of the library is that it’s in very primitive mode at the moment, and some things still need to be tested more thoroughly (and some things are already tested fairly intensively, but you can almost always use more), so it’s not yet released. Right now there are two scripts, and

At this point we can create a basic epub and then compile it immediately and the result passes epubcheck.

as part of the last check-in proclaims.

It’s all GPLv3 licensed by the way. I like things to be open, because then people can patch stuff, or use the library and do other things of their interest, or suggest more in-depth design changes I’m missing out because I’m not an in-depth Ruby-ist, and so on. Not that I’ll listen to all of it (another reason I like things to be open: people can branch). I’m not sure how I’ll deal with things once it all goes Cocoa, but I look forwards to the future with optimism.

(And also to the new Subversion and its changelists. Changelists are godsends.)

(Now is not the time to argue with me about using wxWidgets or the benefits of being truly cross-platform. No, it really isn’t, unless you want to end up quarantined for a while. I care about as much as anybody writing Mac programs cares, which is about the amount you can fill in a thimble.)

(Nor is this time to tell me to use Python, like about the rest of the Epub tools out there use, save for the few in Java. I’ve used Python. I’m probably one of the few people who likes the syntax, in fact, but at the moment Ruby needs a library and I work in Ruby. Pardon me for being selfish, but I am indeed both open and selfish at the same time.)

During all this I ended up learning Rake and part of Gem creation, and also dove a bit more into Ruby, and thus wrote up a couple quick references (now featured on the new Quick! page).

By the way, things about my coding style and approach:

  • Copious comments, unless I’ve obviously rushed things (in which case I feel horrible). One of the first stops I made during my Ruby crash course was to find out how Rdoc worked.

  • Object-orientated, modular design. I really like responsibilities to belong to cohesive units that can be called by other cohesive units. Crazy, I know.

  • I tend not to do wild and crazy kool-kid hacker things, because I like my code to be readable. And yes, some people do think I’m stupid because I don’t use unless or dance around with the trinary operator and bit-mode flags and re-implementing my own XML parser, but whatever.

  • I don’t worry about speed and rock-hard reliability against all edge-cases up front. I add that in later, and because the devil’s advocate unit tests keep failing until I do.