Friday, March 19, 2010

The ePub saga continues

I spent some time cleaning up the HTML and bring it back into Calibre. I started going through the settings and realized that I really should actually read the instructions.

OK. The instructions are reasonably complete and they even have color and pretty pictures. I can do that. What's this? An ePub editor named Sigil? It lets me see the code and control the output? Hallelujah! Let's download that puppy.

It downloaded and installed fine. My kvetchy computer is still stable. Will it open and append multiple HTML files like eCub does? Ah: It does not. No biggie... 10 minutes in Dreamweaver and I'm ready again.

The new HTML file opens just fine. There's a tool for adding chapter breaks. I'm so excited I danced a little happy dance of joy right there in my chair. An automated and editable Table of Contents tool? I'm in heaven.

Except... wait. I can't make the TOC show up.


I take a look at the code.

There are some codes that ID where there chapters break... but there is also a comment that says not to touch them and that they get deleted when you convert to ePub anyway.

Well, phththttp.

The rest of the code looks like straightforward HTML.... which means my "hallelujah ePub app" isn't adding much to what I already had.

OK... the instruction manual helped before, let's try this again. Well, I'm getting deeper into open source stuff, so that means less and less actual documentation. There is a nice set of instructions on doing an initial conversion. I follow them to the letter.


No table of contents.


Frustrated, I walked outside into the beautiful 70+ spring day that I'm totally missing because I'm working on this. Think, Amy, think. Well, the best documentation is on Calibre. Let's to back to that.

I started reading those instructions more carefully. More links to more software. Hmmmm.... here's something that is supposed to convert directly from Word by integrating with Calibre. I know how to format in Word... maybe that will work better. I downloaded BookCreator Tool. That one says if you really want this to work (*grumble*), you need eBookPublisher from yet another place.

I know this dance. It's called the "Open Source Web App Hustle" and it almost always ends up with me laying on the ground with a headache because I've been banging my head on my desk in frustration.

It also almost always winds up with a crashed computer.

*sigh* Well, maybe just two more before I dive back into Calibre.

Hmmm. That's not bad. It was a direct conversion to ePub... it doesn't look too bad. Pity that I've spent the past two days editing the HTML text so that now my original Word doc is significantly out of date.


I'm going back outside.


  1. Hi Amy,

    I wrote the basic Sigil instructions (I'm a contributor to that project as well as one of the founders of, which is a marketplace in competition with Lulu), and I'm curious to know what went wrong in creating the table of contents in Sigil?

  2. I should probably update the post. The Table of Contents worked fine... but I couldn't see it in the Sigil app. The interface didn't give me what I expected. That's what threw me. I had to load it into an ebook reader and then find the TOC button.

    Sigil give me the list of TOC items and lets me edit it -- that's fine. But since I was sort of new to the ebook thing and relying on my experience with TOCs in tradition books, I was expecting the TOC to appear on my working document -- like the images did.

    Sigil is a good app and wound up to be my favorite because of the simplicity and cleanliness of the interface. It would be nice if the app had the instructions built in and having contextual help would be super awesome (though I know how hard this is technically and from a UI perspective). The Google group I got this from seemed more focused on collecting bug issues than informing the user.

    I'll take a look at FiFoBooks. Thanks for the link!

  3. Ah, that's a good point: if you're used to Microsoft Word style TOC generation, you would expect to see a list of chapter entries at the start of your text.

    It's unnecessary, though, as far as the epub format is concerned (instead, if the TOC meta data, as viewed through the TOC Editor is correct, then your book's TOC is valid, and will be visible to reader devices).

    I'll update the tutorial docs to make that point clear.

    Also, good idea about having a specific forum for these types of questions on the Sigil project site, in addition to the current bug tracking one.

    As far as goes, I should also mention that we're currently sponsoring a writing contest where the winner will get $1,500.

    See this link for the details: