This post is part of So You Want to Make an eBook?. I’m releasing this book in sections on my blog, but when it’s all finished I will offer the whole thing as a single eBook. Everyone who donates toward its production (use the coffee cups to the right, note that it’s because of this effort) will get a free copy of this eBook. You can find all the posts here.
Checking Your WorkRemember when I told you to install Calibre? You’ll use the eBook viewer built into that program to quickly scan over your file. Check your font size, your built-in table of contents, and file order. If you find a problem, double-check your work. Remember that a forced page-break may not render with Calibre’s eBook viewer.
Note that the table of contents in the sidebar is correct. This is the built-in table of contents that you created above.Once you’ve done this "eyeball" check, you’ll use the epub-fix tool that came bundled with Calibre. You’ll go to a command prompt in the directory with your eBook and type:epub-fix myebook.epubCalibre should have added itself to your "path" so this should work. The output from this program is pretty straightforward to understand – and to fix. One note: It will usually only list one
error at a time. You will have to run this tool multiple times. Here’s two examples from a real project I was working on:Ops/CoverPage.html not in manifestWhoops. Easily fixed – I left that file out of content.opf. I added it in.Failed to parse: Ops/chapter_07.html with error: Opening and ending tag mismatch: html line 1 and body, line 138, column 8When I had cut-and-pasted the chapters, I forgot the ending </html> tag in some of the files. Whoops.The next program to use is epubcheck. You can either run it yourself (using java) or use ThreePress’
online validator at https://threepress.org/document/epub-validate. Both give the same output; I find the webpage a little easier to read; at least, until I wrote a script that works on Linux: https://ideatrash.net/2011/04/using-epubcheck-on-linux.html If you run it locally, the command line is:java -jar epubcheck-x.x.x.jar myebook.epubThe x.x.x portion is the version number of the program. The epubcheck program does not give back user-friendly output. Here’s some examples (again, from a real project.) along with the reasons why they were errors.
ThreePress’s site also has links to some common explanations of the errors epubcheck finds.ERROR: myebook.epub: length of first filename in archive must be 8, but was 9Remember when I said that the mimetype file had to be the first file in the archive? For some reason, it wasn’t. Re-create a new archive, put mimetype in it first, then in a separate operation, put all the rest of the files for your eBook back in.ERROR: myebook.epub/Ops/toc.ncx(26): assertion failed: identical playOrder values for navPoint/navTarget/pageTarget that do not refer to same targetERROR: myebook.epub/Ops/toc.ncx(32): assertion failed: identical playOrder values for navPoint/navTarget/pageTarget that do not refer to same targetERROR: myebook.epub/Ops/toc.ncx(38): assertion failed: playOrder sequence has gapsThis seems like a frightening series of errors, but it was because I accidentally had two entries with playOrder="2" and then straight to playOrder="4".ERROR: myebook.epub/Ops/chapter_07.html(2): The processing instruction target matching "[xX][mM][lL]" is not allowedAgain, imposing looking. I had a blank line at the top of the file instead of the line that began <xml. Whoops. Deleting that extra line at the top of the file fixed it right up.ERROR: myebook.epub/Ops/chapter_14.html: Malformed byte sequence: Invalid byte 2 of 3-byte UTF-8 sequence. Check encodingERROR: myebook.epub/Ops/chapter_17.html: Malformed byte sequence: InvalidThis was the hardest to track down. This is what I found:"Somewhere in your production chain you have an editor that’s not handling UTF-8 properly and is inserting garbage that’s being interpreted as a UTF-16 surrogate. You need to fix this or you’ll run into encoding errors again in the future."To fix that problem, I opened the affected file in Notepad++ and use that to convert the encoding (in the Format menu). You may need to track down and change the character that’s been mangled by the misbehaving editor. If you’re using another editor, find the appropriate command to do the same thing. Simply saving it as UTF-8 format will usually
fix the problem.One small note – as you fix one problem, more may crop up. For example, the error about "[xX][mM][lL]" meant that the rest of the file wasn’t parsed properly. There were other errors (usually typos) that epubcheck caught after I fixed that big one.
Converting to Other FormatsNow that you’ve got a valid ePub document, you’ll want to convert it into other formats. Specifically, I’m talking about converting your ePub into the Kindle (or .AZW or .mobi, depending on who you’re talking to) format.Let Calibre do it. No, really. Once you’ve made a standards-compliant ePub, Calibre will convert it to the Kindle format like a dream. If your ePub is not standards-compliant (if it doesn’t pass epubcheck or you’ve not bothered doing the hand-coding covered in this book), then you’re likely to get garbage.One note: If you have a PNG with transparency, it will not work in the Kindle format. It will look like a negative of itself, which sucks. So give your PNG a nice light white background instead of a transparency layer and it’ll all be good.Converting is pretty simple. Either drag your ePub file into Calibre’s main window or use Calibre’s "Add book" dialog. Select the book, and click on the "Convert Book" button at the top of the screen. On the next screen, change the "Output Format" box to MOBI. Click OK; the default options should work just fine.
The files will be in the directory "Calibre Library", located in your home ("~/home/YourName/Calibre Library") or user directory ("C:UsersYourNameCalibre Library") depending on your operating system.Congratulations! You have your book in formats that can be read by practically any eReader out there. Now the only problem is getting the eBook to those readers. Luckily, we already covered that here: https://ideatrash.net/2011/04/business-principles-so-you-want-to-make.html
At this point you should be ready to go. This part seems simple, but it’s easily the most time-consuming and frustrating. Google is your friend. And of course, feel free to ask here.
Any questions?
This post was part of So You Want to Make an eBook?. I’m releasing this book in sections on my blog, but when it’s all finished I will offer the whole thing as a single eBook. Everyone who donates toward its production (use the coffee cups to the right, note that it’s because of this effort) will get a free copy of this eBook. You can find all the posts here.