{"id":17842,"date":"2020-11-05T22:59:09","date_gmt":"2020-11-05T22:59:09","guid":{"rendered":"https:\/\/davidgerard.co.uk\/blockchain\/?p=17842"},"modified":"2022-11-26T13:01:35","modified_gmt":"2022-11-26T13:01:35","slug":"calibre-epub-and-epubcheck-the-curse-of-editing-xhtml","status":"publish","type":"post","link":"https:\/\/davidgerard.co.uk\/blockchain\/2020\/11\/05\/calibre-epub-and-epubcheck-the-curse-of-editing-xhtml\/","title":{"rendered":"Calibre, ePub and epubcheck: the curse of editing XHTML"},"content":{"rendered":"

Calibre is an ebook management application. It comes with a nice ebook reader too, which I use all the time. [Calibre<\/i><\/a>]<\/p>\n

Calibre is also the most common ePub generator. Its format converters are robust and battle-hardened.<\/p>\n

This post is a record of what I actually did to make the ePub for Libra Shrugged<\/i><\/a>. There’s almost certainly bits I could have done better some other way, and a lot of bits where I got way too deep into technical twiddling just because I could.<\/p>\n

(Comments suggesting using LA<\/sup>TE<\/sub>X instead will get you slapped over the Internet.)<\/p>\n

If you don’t understand any of the technical detail here, don’t worry about it \u2014 there must surely be better ways than this.<\/p>\n

 <\/p>\n

\"\"<\/a><\/p>\n

 <\/p>\n

The horror<\/h3>\n

Since this is on computers, there are some gotchas \u2014 specifically, that ePub is an absolute shower of a format, and you will<\/i> be editing XHTML by hand if you want to get onto Apple Books and the other minor ebook stores.<\/p>\n

The good news is that Calibre has a pretty good XHTML editor \u2014 right-click on book title, “Edit book”. The bad news is that you’ll need it.<\/p>\n

If you’ve lived your life wrong enough that you’re hand-editing ePub XHTML, you should probably install epubcheck. There’s an online version, but I just installed the Java .jar<\/tt> file locally \u2014 it’s much faster. [EPub Validator<\/i><\/a>; <\/i>Github<\/i><\/a>]<\/p>\n

The developer of Calibre considers epubcheck broken, which it is, and wrong about the ePub specification, which it is. Unfortunately<\/i>, Apple Books requires your book to pass epubcheck anyway, with no errors or warnings. [Apple<\/em><\/a>]<\/p>\n

At one point I unzipped the ePub into separate XHTML files. This let me hand-tweak the files directly in vim, then add them back to the ePub using zip -f<\/tt> (freshen). Nobody who isn’t me should expect to have to do this sort of thing, but I’m a control addict.<\/p>\n

(I\u2019m using zip -f<\/tt> and not just making a zip file of the separate files because that way, the mimetype<\/tt> file stays both uncompressed and first in the zip file \u2014 if it isn’t, epubcheck complains. ePub is weird and annoying.)<\/p>\n

Getting Calibre<\/h3>\n

If you have Windows or Mac, just download the latest version (5.4.2 as I write this) from Calibre and use that. [Calibre<\/i><\/a>]<\/p>\n

Update 2022:<\/strong> Ubuntu 22.04’s distro version of Calibre works fine. sudo apt install calibre<\/tt> and ignore the rest of this section, you lucky person.<\/p>\n

I use Xubuntu. Unfortunately, Ubuntu 20.04 has a broken version of Calibre that can’t possibly start or work \u2014 Ubuntu pulled a development version from Debian, nobody noticed before release time that it literally didn’t work at all, and now the broken version’s stuck in place for the next five years. [Launchpad<\/i><\/a>; <\/i>ubuntu-devel mailing list<\/i><\/a>]<\/p>\n

(The broken version still has a functional ebook-viewer.)<\/p>\n

If you’re like me and insist on using Linux, you can run the Linux install instructions without<\/i> running it as root. I did the isolated install per the Linux download page: [Calibre<\/i><\/a>]<\/p>\n

wget -nv -O- https:\/\/download.calibre-ebook.com\/linux-installer.sh | sh \/dev\/stdin install_dir=~\/calibre-bin isolated=y<\/pre>\n
(Calibre doesn’t offer distro packages, because the author has had so many bug reports from broken distro versions that he tells users to get the official binary instead.)<\/p>\n
After installing Calibre to my home directory in this way, I start it from a terminal.<\/p>\n
Convert your DOCX in Calibre<\/h3>\n
I wrote both books in LibreOffice in its native ODT format. Calibre’s conversion of LibreOffice ODT files is much better in 2020 than it was for Attack of the 50 Foot Blockchain<\/i><\/a> in 2017.<\/p>\n
But I wanted clickable indexes \u2014 so I saved the book file in LibreOffice as DOCX, and sent that to Calibre for conversion.<\/p>\n
This is the easy part. You click the “Add book” button to import the DOCX, you right-click on the book name and go Convert books\u2192Convert individually.<\/p>\n
Choose the following options:<\/p>\n