Adventures in creating an ebook

12 years ago

As I mentioned a week or so ago, I discovered that my book, The Tomes of Delphi: Algorithms and Data Structures, was out as an ebook. And that, since the ebook was mostly created from a mechanical process converting my PDF for the physical book, it was pretty grim formatting-wise. So, over the past 10 days (not continuously, I hasten to add), I’ve been recreating it.

Having tried to use Scrivener (for Windows, not the Mac version), I abandoned it for Jutoh, based on a recommendation from Jeff Duntemann. The main issue I had with Scrivener is that it didn’t have stylesheet support, and I’ve used (and grown used to) styles in Word for some 15 years or more. The original manuscript for the book (which I started in 1999, although it was only published in June 2001) used styles heavily. So switching back to a word processor that didn’t support them was way too much of a culture shock. So, Jutoh. This program is just for writing books for e-publishing and works pretty well from my viewpoint, although I did find several user experience problems (I’ll talk about them in a future post).

I imported the EPUB file that Lulu had created so that I had somewhere to start and then investigated the job that needed doing. My plan of attack was to firstly define the look I wanted by editing the stylesheet, and then to go through the entire manuscript setting paragraph styles, required italics in the text, and replacing every single code listing (this was the major problem with the mechanical EPUB conversion: indents in the code were completely lost).

I decided to use the Body Text style for the main text, the various Heading N styles for the four levels of heading I had, the Caption style for figure, table, and listing captions, and HTML style for the code listings. That latter choice seems odd, but it was a monospace paragraph style and it caught my eye, and so I used it instead of creating my own. That was my first big mistake.

The formatting and copy/pasting was simple, if tedious to the nth degree. I worked on two screens: the original Word document open on one and the Jutoh project on the other. I’d scan from one to the other to make sure I identified all the required italics, and to copy the code over. Over the 12 chapters, I suppose I averaged around 90 minutes per chapter, taking around 18 hours all told.

After that was complete it was time to compile the ebook. The first time I did this, I had zillions of errors. The Table of Contents from the Lulu EPUB was all screwed up for some reason, but the next error was even more bizarre: it was the first code block and didn’t have any HTML markup generated for it at all.

A quick aside is in order. The EPUB format is essentially HTML plus supporting CSS, with some metadata added to make sense of the individual HTML files. The whole folder structure is then zipped up and renamed to a .epub extension. The mobi format for the Kindle is the same way. So you are in fact going to generate a “web site” that will be your book. Jutoh hides this to a certain extent (the Jutoh project file is a SQL Lite database of binary blobs and text), and then will generate the required HTML/CSS when you compile the book.

This HTML markup problem just flummoxed me. I had no idea why the style wasn’t generating the required markup. It turns out that the HTML style is a special Jutoh style that says “output the content directly to the resulting HTML file with no processing or conversion”. The wacky thing is that the Edit Styles dialog allows you to modify the HTML style ad nauseam (I’d changed it to have a grey background) without warning you that it would have no effect. Or, even better, just making the HTML style non-editable. Once I’d worked that out (RTFM, Bucknall), I created my very own style (called, imaginatively, “Code”) and replaced the HTML style with my own style (yes, luckily there is a find/replace dialog for styles).

(Aside: it turns out that I should have called the “Code” style “Preformatted Code”. The word “Preformatted” in a style instructs the compiler to output the content in a <pre> tag. Oh well. That’s my second mistake.)

The Table of Contents problem turned out to be easy to fix: I just got Jutoh to recreate the ToC completely.

After those two biggies, the remainder of the errors were minor and simple to fix and I suddenly had a clean-compiled EPUB file. I launched it within Adobe Digital Editions, the EPUB reader for PCs. It looked pretty good, so it was time to check it on a Nook!

On Thursday last week, I’d popped into my local Barnes and Noble and bought a Nook Tablet, and basically got a cover for it for free by using my B&N membership card. It was all ready for the big experiment. I connected it to my PC, copied the file over to /My Files/Books, disconnected, and then spent five minutes trying to find it on the Nook. (Hint: hit the nook button, go to Library, My Stuff, My Files, Books, and there it will be). It looked OK, except…

The images were too large. The code was in a serif font. And worse…the code had lost its indentation again. To say that I yelled Arrrgh was about as polite as I can be.

The code, as you might have gathered, should have been re-styled as “Preformatted” instead. I, in my desire never to read a help file and find this out, replaced all spaces in the code blocks with non-breaking spaces. Yeah, Nook, take that! Well, it cured the indentation problems, but the code was still displayed in a serif font. I found the “Publisher Defaults” slider in the Text options for the Nook, and flipped that to On, which not only displayed my code listings with the grey background I wanted but also in a monospace font.

But the images were still getting cut off for being too big, including the book cover. Grrr.

For grins, I went back to Jutoh and compiled the book to a MOBI file and downloaded that to my Kindle Fire. The images displayed perfectly. Ditto the code listings: I didn’t have to futz around with a “display the book as the publisher wanted” button as on the Nook. The same went for the 2nd-gen Kindle Reader I own. Maybe Kindles just do a better job than the Nooks as a reading device.

Anyway, more research was needed: how to generate the EPUB so that the Nook will display the images properly. At this stage I really didn’t want to regenerate the forty or so images in the book to have a maximum width of 580 pixels (the recommendation that B&N give). Turns out that Jutoh has an option to rescale images during the compilation phase (it’s under Book | Project Properties | Configurations: set the Maximum Image Width to 580 and be done with it).

So that was that: I uploaded the compiled EPUB file back to Lulu (since they set it all up, they can republish it to B&N and to iTunes), and I went to the Kindle Direct Publishing site and created a new project there and uploaded the MOBI file. It’s “In Review” at the moment but should be available tomorrow. I also set up my Author page on Amazon so that it’s ready to promote the ebook when it’s available.