Mars to Stay: Discovering the wonderful world of EPUB

It’s been a little quiet here on the blog, so let me share an update on where I am with Mars to Stay, my story game about the first Martians pursuing the dream of a colony on Mars.

For the online version of Mars to Stay, I used GoogleDocs to edit and share the text. While GoogleDocs isn’t as feature rich as MS Word, it’s great when you want to focus on the content and when you want to share the text with reviewer and play testers (don’t get me started on O365 and the web version of Word). This worked great to get the content as I want it, and it can do a decent job of formatting a pdf for print. Embedding images and controlling size and placement were also not too fiddly.

A manned rover exploring Mars by Claudia Cangini. The scattered remains of previous missions reveal that things don't always work out as easy as you hope.

Let’s get it on Lulu

So with a pdf ready, from there to self publishing on Lulu should be an easy ride. Right? Well, then I got into the wonderful world of the EPUB format. While an EPUB file is basically just a zip file with a bunch of xhtml-files, there is of course a little bit more to it than that before you have a clean file that will pass the quality criteria required for publishing and distribution. 

Lulu requires a file in EPUB format with meta data such as ISBN number set correctly. While Lulu offers a tool to create an EPUB file based on a MS Word docx file, I really didn’t feel like letting go of my Mac (or installing Word for Mac, enough said). 

Generating EPUB format with GoogleDocs

GoogleDocs can export also to EPUB so I went down that path.

A text like Mars to Stay contains a lot of lists and tables, so besides the nice images I commissioned from Claudia, it took a lot of iterations to get an EPUB file that would also render decent just on the Macs default EPUB viewer. Sections that looked the same in GoogleDocs that absolutely didn’t in the EPUB viewer. While GoogleDocs has some support for managing style sheets, it has its shortcomings.

I was soon to discover one more: When I finally had a decent looking EPUB, I created a project on Lulu for Mars to Stay. Title, ISBN, author, description etc. were all checklist tasks. But when I uploaded the file, a check complained that title and ISBN in the EPUB meta data didn’t match with what I had entered. There is no way to set the meta data in GoogleDocs and have it included in the export. 

So how about editing the generated file? It’s just zipped xhtml-files, right? Well, the generated EPUB file from GoogleDocs isn’t exactly humanly readable. Pages, the default word processing tool on Mac, allowed me to edit the meta data for title but not isbn. 

Calibre to the rescue

Browsing the internets revealed two candidate EPUB editors for Macs, hidden behind a wall of “we will fix your EPUB format for you” promises (a warning sign that this would not be as easy as I hoped). After convincing Apple that these open source programs not appearing in the App Store is perfectly safe, I got one of them, Calibre, up and running and have now taken it for a spin on Mars to Stay.

These are features I have found useful so far:

  • Merge identical style definitions. It looks like GoogleDocs creates one instance of a style definition per instance in the document and they all have generated identifiers which makes it practically impossible to get to a consistent layout by editing the source. By merging duplicate entries, it’s still tedious but at least possible. 
  • Find broken links. Fixing them is also doable.
  • Resize images. One of the formatting requirements on the publishing list is that embedded images are not too large (quite opposite from publishing for print).
  • Edit meta data like isbn. Hey, this is what I came here for!

Other nice-to-have features I have found are Smarten punctuation, Word count including frequency, and the Table of Content editor. You can feel when software is created by someone who needed it to do the job themselves.

The Check tool finds broken links much faster than testing each link as I've already did multiple times.
A list of auto complete suggestions makes it possible to navigate in the generated anchor names.
Why make it complicated?
An option to inspect the changes made by the tools give you full control of what happens. The Smart punctuation tool suggests to replace quotes and ellipses in this screen shot.

Back on track

So the project is back on track for a planned release any time soon. In the mean while, NASA’s Perseverance rover has sent images and sounds from Mars and the first flight on Mars is imminent