OPF Patcher

Do you know what's great? Automating things. When I was writing Shepherds, one of the things I wanted to get sorted was automating the whole build process, so that if I made a change, I could build PDF, EPUB, and MOBI files without tinkering with all the bits in between. I'll talk about that whole process in the next blog post.

This one is a specific step in that process; patching the OPF file.

Why is this a thing?

Most of the gruntwork was handled by the amazing Pandoc, which if you don't know it, allows you to convert pretty much any type of document into any other type of document.

The plan was to take the EPUB generated by Pandoc, run it through KindleGen and have a functioning MOBI file.

That said, the prevailing advice from Amazon right now is to upload your MOBI and cover separately and they'll combine it into the final product. I was having problems getting the Cover link working in Kindle for Android (it did work on other devices though), so I assumed this was the problem.

If you've ever generated a MOBI by hand, then you'll know that the cover is declared in the OPF file along with the other assets that make up the file.

An EPUB is a glorified zip file, which meant I could unzip the contents, modify the OPF, then rezip and use that modified EPUB to generate my MOBI. That said, I'm not really bothered doing this every time - as I said, I'm all for automating the boring crap.

Enter Node.

Node is essentially a JavaScript runtime that's mostly used for building online services, though it can be used offline. I've recently discovered a love for building quick tools in JavaScript as it's a great hacking language, so I set up to build OPFPatcher

So what can it do?

OPFPatcher can:

• Optionally remove the cover declaration. I left this optional (default is yes), as you might want to distribute MOBI files outside of Amazon, in which case you'll want a cover
• Optionally add a link for the start of the book so that when readers first open, it starts in the right area
• Optionally add a link for the dedication section
• Optionally add a link for the acknowledgements section
• Optionally add a link for the back-of-the-book section

All the extras come from having a quick look at what Kindle supports. They add extra sections in the menu allowing readers to jump to a few parts of your book. Having the Kindle open your file at the start of the book is also pretty useful if you've a few miscellaneous sections at the start of your book.

How can I use it?

All interaction is via the command line, so you'll need to be familiar with a terminal or not afraid to learn (trust me, once you start seeing what you can do with it, you'll want to automate everything).

Once downloaded, there are two ways you can use it:

Use a pre-built exe

Inside the bin folder you'll find pre-build exes for a few target platforms (Mac and Linux are on hold until I can get my hands on a machine again). Simply target the exe in your batch/command prompt and you're good to go (examples below).

Work from source

You'll need Node installed, obvs. Then go to the folder where you've downloaded the source, open a command prompt and type:

npm install

If you'd like to be able to use it from anywhere, then use:

npm install -g

You can then call it using the opfpatch command.

Examples

Type opfpatch --help (or PATH_TO_EXE/OPFPatcher-win-64.exe --help) to get a full list of the commands and what they do.

To simply remove the cover and nothing else:

opfpatch -i PATH_TO_OPF.opf --cover-html my-super-cover.xhtml

If you don't know the name of the cover html file, you can find it by unzipping the EPUB. Generally I do this so I can see where are the sections are mapped to, so I can add them to the OPF.

To leave the cover, but add the start of the book as an entry in the guide:

opfpatch -i PATH_TO_OPF.opf --book book.xhtml --book-title "Start of book" --keep-cover

Here --book specifies the file that holds the start of the book. You can also use anchors if necessary: --book bigfile.xhtml#start. --book-title is the title to use for the menu.

A full example, which removes the cover, and adds start-of-book, dedication, acknowledgement, and back-of-book sections (e.g. a build for Amazon):

opfpatch -i PATH_TO_OPF.opf --book book.xhtml --book-title "Book" --ded ded.xhtml --ded-title "Dedications" --ack ack.xhtml --ack-title "Acknowledgements" --bob bob.xhtml --bob-title "About the author" --cover-html my-super-cover.xhtml

Any questions, get in touch!

Find all the code and executables on Bitbucket

You can download the pre-built exes or the entire codebase if you want to tinker with the internals

Download