Producing an ebook is one of the more confusing parts of self-publishing. Guides offer all kinds of suggestions for DIY software and companies who’ll create the ebook for you.

I chose to create my own ebook for a few reasons: (1) to save money, (2) to learn something new, and (3) because Bread Science is complicated. I wanted the index of Bread Science to link back into the book, but without page numbers, I had to choose which word each index item would link to. I also had to move the 200+ pictures to be in-line in the correct place in the text, and to modify the text in places to match. I thought it might be impossible for someone else to make these changes correctly, or at the very least it would cost a fortune.

But recently I had to look at the code of my ebook. (While I have never found a problem with it, running it through an “ebook validator” showed six errors, and this prevented the ebook’s acceptance at OverDrive [via Kobo], the ebook service libraries use.) I’m sharing the experience here.

Methods of Creating eBooks (as far as I can tell)

1. Create a Word document, format it properly, and convert it using conversion software (like Calibre) or upload it at a sales site (Kobo, KDP, etc.) and let them convert it. This seems like the most accessible method to me.
2. Create an InDesign document, format it properly, and export it as an EPUB: I’ve been told this is a thing, and preferred by professionals, but I have no idea how this works! I’ve only used InDesign as a page layout program.
3. Create an EPUB by writing code. Yikes.
4. Pay someone else to create an EPUB,
5. Use method 1 or 2, then tinker with the code to make it better. This method is what we’re exploring here.

eBook Code

I’m not an expert so i won’t try to explain this in detail, but basically, what’s behind an ebook is code similar to a web page’s code. When you use a program to convert a Word document to an ebook, the program creates that code. Your proper formatting of your Word document results in good code.

There are probably people out there who can write that code straight out of their heads. Most people, though, create the code using a conversion program and then tinker with it. Calibre has an ebook editor, so I decided to start there, since I’d used Calibre to create the ebook.

When I opened Bread Science in the ebook editor, it looked like this:

Fixing the Errors

The staff at Kobo had helpfully sent me information about the errors in my ebook. (I later realized that I could find these errors by uploading my ebook to a free online ebook validator.) Two of the six errors looked something like this:

ERROR RSC-005 /index_split_012.html (line 24, col 33) Error while parsing file ‘attribute “value” not allowed here; expected attribute “dir”, “id”, “lang”, “style”, “title” or “xml:lang”‘.

Initially I had no idea what these errors meant. You can see that each error contains a location: an html file name, and a line and column. I opened the file (index_split_012.html) in the editor and looked at line 24.

You can see that the code for list item 9 (in the box) differs from the code for the other list items, and there is a corresponding odd indent in the ebook. The code is extra confusing because some of the items are bookmarked and linked to from the index (that’s what the blue ids are for) but some are not. List item 9 (“Cooling”) is not linked to from the index.

I altered the code to match the code from line 19 (list item 5: Fermentation), because this list item also does not have a link from the index. This removed the error.

So basically, I never really understood the error in technical terms, but I was able to adjust the code using nearby samples.

Two of the errors looked something like this:

ERROR RSC-012 /toc.ncx (line 30, col 58) Fragment identifier is not defined.

This turned out to involve a table of contents (TOC) item, the dedication page, that was missing its bookmark. So, the converter (rightfully) got confused and pointed the link to the dedication page at the title page instead. I manually added the bookmark code, and in two places corrected the link (sending it to the dedication page, index_split_004.html, instead of the title page, index_split_000.html).

The final two errors looked something like this:

ERROR RSC-005 /toc.ncx (line 20, col 58) Error while parsing file ‘identical playOrder values for navPoint/navTarget/pageTarget that do not refer to same target’.

The file toc.ncx appears to be one loooong file. It’s related to the table of contents, and it doesn’t produce a preview. Note that each item in the list has a “playOrder” that increases one by one, but the error occurs when playOrder=“2” repeats. (You can also see the index_split_000, which I changed to index_split_004, as mentioned above.)

I think this error occurred because my Acknowledgments and Dedication are two items in the TOC, but I did not insert a page break between them as with all the other TOC items. I had to search the error online to figure this one out. It appears that a playOrder number cannot point to two different locations. Even with the “000” corrected to “004” I still had two different locations: index_split_004.html and index_split_004.html#id_Dedication.

So I had two choices: change the second location to match the first (in which case readers clicking on “Dedication” in the TOC would be taken to the top of the page, and would have to scroll through the Acknowledgments to reach the Dedication at the bottom), or renumber all the playOrders manually. I did the latter.

Success!

I uploaded my tinkered-with EPUB to an ebook validator and it passed the test. I still find working in code daunting, but at least now I know what it means to tinker with the code, and I was able to make some quick fixes.