Take a very deep breath, because we’re about to do a deep, deep dive!

This post describes the NCX file. The NCX is an adjunct file in addition to the Table of Contents (TOC) file that performs somewhat like a TOC on some Kindle devices. If you use the Kindle Previewer to look at your MOBI file, you’ll see three icons along the top, just to the right of the big A for resizing the font. The first icon takes you to the cover page. The second takes you to the book’s regular table of contents. The third takes you to something called the “NCX View.” In order to have something for that icon, you need to create an NCX file. In passing I point out that my iPad Kindle Reader doesn’t seem to make any use of this capability, but I suppose other Kindles do. And Kindlegen is perfectly happy to create your MOBI file without an NCX (I’ve done it). But, here we are, determined to give Amazon their due!

So…on to the NCX file. It is referenced in the OPF file. The NCX file itself is conceptually simple. Note the word “conceptually.” Everything has to be exactly perfect for it to work. The example NCX file shipped with Kindlegen 1.2 is a good place to start. For reasons known only to God and Amazon, no sample files are part of the Kindlegen 2.0 package.

The elements are in this order:

<?xml... (you can just copy from the sample file below or better yet from the sample files that came with Kindlegen 1.2)
<ncx>
<docTitle>
<docAuthor>

… repeat this as many times as you want…

</navmap>
</ncx>

Seems so easy, right? Clearly, the important items are the navPoints. Each navPoint is an item in the NCX navigation feature. Note that navPoints can be nested, for example to create Chapter 2.1 or Appendix 3.1.3 or whatever. I have a TOC that’s only one deep, so we’ll skip the nesting for now. Let’s take a look at each element of a navPoint.

First, the navPoint label itself. Here’s an example of two:

<navPoint class="toc" id="toc" playOrder="1">
<navLabel>
<text>Table of Contents</text>
</navLabel>
<content src="tuttoc.html"/>
</navPoint>

<navPoint class="chapter " id=" 1" playorder=" 2">
<navLabel>
<text>Chapter 1: The Electric Sword 1</text>
</navLabel>
<content src="tut.html#__RefHeading__34774_658303778"/>
</navPoint>

Okay, the navPoint label itself. It contains a class="toc" item. Honestly, it doesn’t seem to matter what you put in there. Note that in the second example above, it’s just "chapter ". I toyed around with different things and it didn’t seem to make any difference. So just make it what you feel like. Next comes the id=" 1" tag. Similarly it seemed I could put about anything in there. But the next tag, playOrder="1" tag is critically important. You want to put these in numerical order, starting with one and incrementing until you’re done.

Now the navLabel tag. It seems to have only one content item, and that item is in between the text tags. This text is important, as this is what is displayed in the NCX display, verbatim.

Next comes the <content src="yourhtmlfile.html"/> item. This is stunningly important. This tells Kindlegen the exact location of what it’s pointing to. Note in the first example above it points to “tuttoc.html”, which is the separate TOC HTML file. But it’s the second example that’s more important. It reads:

<content src="tut.html#__RefHeading__34774_658303778"/>

Let’s deconstruct this. The scr obviously is a pointer to the location. The first part, tut.html is obvious—it’s the main body of my book. But notice the #__RefHeading__34774_658303778 part. The hash mark (#) is critically important, as this is a reference to a specific place inside tut.html. In this case it matches up with an element in tut.html that looks like this:

<a name="__RefHeading__34774_658303778"></a>

(without the hash mark). Your word processor’s TOC feature actually inserts these, but only if you tell it to so that your TOC is hyperlinked. (Heaven forbid you have to put these in manually!)

Now, you say, isn’t all this information already in your toc.html file? The answer is a resounding “yes!” But your TOC is in HTML format. So, you are faced with the incredibly tedious task of converting by hand, or you can write a little piece of software to extract the info from your TOC file and create the NCX file. (Can’t Kindlegen do this for you? Apparently not.) So, in fact, I created a little piece of software, written in BASIC (use the FreeBASIC compiler with the -lang qb feature), which you’ll probably have to modify to meet your needs.

Okay, that’s all there is to the NCX file. Kindle’s example OPF file claims that the NCX file is mandatory, although I’ve created a MOBI file with only the toc.html file. But if you want to forge ahead, here’s my example NCX file, followed by my example BASIC program to turn an HTML TOC file into an NCX file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ncx PUBLIC "-//NISO//DTD ncx 2005-1//EN"
"http://www.daisy.org/z3986/2005/ncx-2005-1.dtd">

</navmap>
</ncx>


And here’s the BASIC file. Note that I stuck the initial several lines into a handy file called “startncx.txt”, which just copies the first several lines of the example verbatim.

rem * this program reads tuttoc.html and creates tut.ncx
open "startncx.txt" for input as #1
open "tutbas.ncx" for output as #2

close #2
input "Enter an integer to continue",w
end

Good luck! I look forward to your comments!

1. Prepare a directory where you’ll do all your work. Copy (don’t move, but just copy) all the relevant files to this directory, such as your original DOC or ODT file, and any images you plan to add to what’s already in the DOC file. Your OPF and NCX files go here too.
2. Copy kindlegen.exe from wherever you downloaded it to the same directory. You can go to your download directory, locate kindlegen.exe, right-click on it, and select Copy. Then go to your working directory, click in the white space, and right-click again. Select Paste.
3. Prepare your HTML as usual. Make sure that the html file and all associated images end up in your working directory.
4. Now, here comes the tip. Click in the white space in the working directory. Then, hold down the Shift key and at the same time right-click on the white space in the working directory. This gives you several options. The one you want is the option to Open command window here. Click (normal click) on this option. A command window (DOS window) opens right there, already pointed at your working directory, so you only have to type kindlegen myhtmlfile.html into the command window to invoke it.

That may sound a titch complicated, but actually it’s easier than the convoluted Amazon instructions. Give it a try! And thanks to Ellie O.!

(BTW, I’ve discovered that in Windows 7, this works only if you’ve navigated directly to your working directory. Getting to your working directory via a Library seems to keep this trick from working.)

As nicely as I could, I told the tech support person that words like “astounded they can’t fix this problem in a month” and “incompetent” come to mind.

Here’s the deal. I have their 7 Mbps service, which actually means (in their interpretation—this is a non-standard interpretation) that I get 5 Mbps down and 2 Mbps up. Sometime in the first week in December, 2011, this was reversed, meaning 2 down and 5 up. I’ve been calling in every few days to see what the status is. The plain fact is that someone updated a parameter somewhere and it’s causing this problem not just for me, but for other customers in the area. (I know this for a fact—I spoke at length with one who’s being given the same non-answer I’m getting. Skybeam has also told me that this affects several customers in my area. And, yes, they’ve looked at the configuration of my telephone adapter, which also serves as my home router, and the radio up on the roof. A Skybeam service representative has been to my home twice, both times telling me it’s a “network problem” and something he can’t fix.) My service acts just like it should for a healthy link: low ping times, good VoIP telephone service (I use Skybeam’s offering), and few outages. But, the downlink limits me to 2 Mbps, just as it would if that’s were all I was paying for. But that’s not what I’m paying for. (For completeness I add that they’ve comped me a couple months.)

A month to find a stupid configuration error like this? Good grief! There aren’t that many pieces of equipment between me and where Skybeam hooks into the larger internet.

I live in a very rural area. I’m grateful that Skybeam provides Internet service. But I do lots of stuff over the web and 2 Mbps is simply inadequate. I can’t even watch my own YouTube videos without pausing them and waiting several minutes for them to load enough to play.

Until early December I recommended Skybeam. Several people started Skybeam service at my recommendation. Now I am pointing people away from Skybeam to whatever alternative they can find. At the moment I can’t find an appropriate alternative. The moment I do so, I plan to jump ship.

You’ve just completed a huge project! And now you’re ready to become a licensed operator. But getting that license is not the culmination of your journey—on the contrary it’s only the beginning!