Blog

Incrementing numbers in NCX

Posted on

While the EPUB 3 is slowly taking over EPUB 2 in real-world development, backwards compatibility requires the inclusion of an NCX file inside an EPUB 3 so that older reading systems can still display the Table of Contents properly.

Before we start, take a look at this sample NCX file from The Book of Texas, a sample EPUB 3 file I have made available on GitHub.

In the NCX, note that each item, whether it is in the NavMap (TOC) section or in another section like PageList has both an ID and a playOrder. For example:

<navPoint id="navPoint-1" playOrder="1">
<pageTarget id="pagev" type="front" value="v" playOrder="16">

One of the most frustrating things about NCX creation and editing is re-numbering the PlayOrder values. According to the NCX specification, these PlayOrder values have to be numbered sequentially from the top of the file to the bottom. So, what can you do if you create an NCX file and then realize that you need to add a new item to your TOC, or you add page numbers and need to give them sequential PlayOrder values, as well?

The easiest answer is to use a Regular Expression. Regular Expressions (RegExes, also known as GREP) are a powerful search and replace function available in most code editors, as well as in some programming languages. I always highly recommend that anyone who is interested in creating eBook files learn RegExes, as they can easily reduce the amount of time you have to spend editing eBook HTML by hours. Yes, hours.

RegExes are powerful, but they are not always implemented the same way, so it is important to look at the capabilities of your own code editor before diving in. Usually the program’s Help files will have some information on how RegExes are implemented in the program, with a list of acceptable commands. Here at eBook Architects we use Sublime Text, a cross-platform code editor that has great core features and an active development cycle, as well as many add-on packages that allow you to customize the program to fit your needs.

However, Sublime Text does not natively support the Regular Expression replace option for incrementing numbers. To make that function available, we created a plugin for Sublime Text 2 called Incrementor that allows you do do a Find/Replace with incremented numbers. That plugin was later updated for Sublime Text 3 by another developer.

Incrementor is very easy to use. Once it is installed, press the special hotkey combination to bring up the Find dialog. You can use a RegEx to find all of the values you need to replace in the file, such as:

playOrder="[0-9]+"

Press Enter, and the Replace dialog will appear. In the replace field, use the \i operator to indicate where you want the sequential number to be placed, such as:

playOrder="\i"

Press Enter again, and you’re good to go!

Note that the increment function may also be available in other code editors, so be sure to check the documentation for your favorite one before going to the trouble of installing Sublime Text.

For more information on adding a PageList to your EPUB 2 and EPUB 3 files, be sure to check out the FlightDeck Handbook.


Leave a Reply