When I was looking up the Murderbot series I realised that there were a couple that I’d not read. Two turned out to be short stories (one for Wired and one for TOR) and both were available on the web.

However, “on the web” is not on my Kindle and in Calibre, so I thought about converting them into EPUBs - but how? My thoughts, naturally, went to Org mode and when I searched there was indeed an EPUB exporter. I also checked and both have covers (one fan made).

Install the epub exporter

Installing the EPUB exporter is as easy as adding the following to your emacs configuration:

(use-package ox-epub
  :load-path "lisp/ox-epub"
  :demand t)
Aside 1
Why the :demand t? use-package normally defers loading of packages until they are needed, however, this isn’t a package, it extends orgmode, so we demand it to be loaded
Aside 2
Why the :load-path? You’re going to have to read the Testing and bug fixes section below.

Create a snippet

Reading the documentation I realised that where were some options that need to be set.

UID
a unique id of the document, otherwise known as uri, may be a url
DATE
the date of the document
AUTHOR
the document author or editor, the creator in the EPUB spec
TITLE
the document title

There were also some optional properties that I thought I might want to set:

Subject
the subject matter of the book
Description
a description of the book
Publisher
the publisher of the book
License
the rights associated with this book, the copyright notice, etc.
EPUBCOVER
the cover image to use for the export

So, the easiest way was to create a snippet for yasnippet (I save this in ~/.emacs.d/snippets/org-mode/epub):

# -*- mode:id snippet -*-
# name: EPUB export headers
# key: epub
# --

#+TITLE: ${1}
#+UID: ${2:`(org-id-new)`}
#+DATE: ${3:`(me/date-iso)`}
#+AUTHOR: ${4:Stewart V. Wright}
#+EPUBCOVER: ${5}
# #+Subject: the subject matter of the book
# #+Description: a description of the book
# #+Publisher: the publisher of the book
# #+License: copyright notice and further rights

Testing and bug fixes

I did all of these steps and then generated an EPUB. It didn’t open.

So I started to dig into it… I downloaded epubcheck, I downloaded the latest openjdk container for docker (docker pull openjdk:latest) and then tested the EPUB I generated.

One of the errors was:

ERROR(PKG-007): sample.epub/mimetype(-1,-1): Mimetype file should only contain the string "application/epub+zip" and should not be compressed.

I looked at the sample EPUB in the ox-epub repository (did you know that EPUBs are simply zip files?) and realised that the file I was generating had a new line in the mimetype file. This made me think for a bit and I remembered that I have require-final-newline set in my Emacs configuaration - this option puts a newline at the end if there isn’t already one there. In most cases this is what I want…but not here.

So I modified ox-epub and submitted a pull request. Whilst that is not merged, you can use my modified version of the code.

Finally

Now I have my two new Murderbot stories, ready for reading on any of my devices.