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:


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:


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.

Changes at eBook Architects

Posted on

Effective January 1, eBook Architects will be closing our Austin office as we transition away from eBook development services and re-focus on tools, teaching, and consulting work. Our core staff, myself included, will continue our work within the Firebrand organization, and FlightDeck, our ground-breaking EPUB testing and validation tool, will remain in active development.

When I started eBook Architects in 2008 there were few eBook development options for authors and small publishers that did not involve HTML coding or dealing with the consistently bad quality of the few tools available. Since its beginning, eBook Architects has been promoting the creation of the highest quality eBook files through professional development services, training, and teaching at industry workshops, and through the tools we have released and supported, like Incrementor and FlightDeck. Our acquisition by Firebrand last year brought us under the umbrella of a solid, respected publishing software and service provider with the same passion we have for the quality of eBooks and for our customers.

Over the last few years, the eBook world has been evolving in big ways. Our industry has seen a plateau in eBook sales, the release of a number of DIY and professional eBook creation tools, and consistent increases in the quality of eBook development by a few of the many low-cost overseas eBook creation companies. These changes have made it increasingly difficult for eBook Architects to continue to offer eBook creation services here in the U.S. with the high level of customer service we have always provided and our heavy focus on quality eBook coding.

So, the time for transition has come. We will discontinue our eBook development services, and re-focus efforts on the important tasks of consulting, training, and developing tools like FlightDeck. Our mission of encouraging the entire industry to develop higher-quality eBooks that can stand the test of time and impact readers everywhere will not change.

eBook Architects lives on! I am excited that eBook Architects will continue to be a resource for publishers and authors and a voice for the creation of high-quality eBook files, regardless of how they are created. We will continue to attend and speak at industry conferences, and are available to help publishers and authors with advice, quality assurance, training, and brainstorming. Please do not hesitate to contact me anytime if we can assist you in any way, and be on the lookout for some great things to come down the road.

Low-budget eBook Development Tips

Posted on

eBook creation is complicated, but many publishers and authors have pretty small budgets set aside for their eBook development projects. While we always recommend that you plan your eBook development as part of the larger book creation budget, that is sometimes still not enough to pay for high-quality eBook creation.

If you are stuck in this situation and you have to figure out how to make do with a smaller eBook budget, here are some tips to ensure your eBooks do not suffer.

1. Don’t DIY. The first reaction many people have in these situations is to say “I’ll just do the eBook development myself.” That inevitably leads to many, many hours messing with “automatic” formatting tools, trying to understand techno-speak in the eBook format specifications, and banging your head against the wall every 10 minutes. Your time is valuable, too, so be sure you are taking that value into account when you make your eBook development plans. The same is true of the poor designer you task with this job. If he/she needs to spend 10 hours on an eBook project then you are probably better off sending it to a professional.

2. Choose developers wisely. If you must go to another eBook development company to have your work done (we’ll try not to be sad), be sure to pick someone who has a solid reputation and is available to assist you if you need help. Also, look at their terms of service and understand what they will fix if something is wrong with the files you receive.

3. Quality Assurance. Regardless of who does your eBook development, you know your content better than anyone else. Plan in advance to spend at least a few hours looking through the eBook files on different devices and making sure that the conversion was done properly. You will need to educate yourself on how to do this well, but it is worth the effort.

4. Get professional diagnostics. If you are concerned that the eBook files you paid for are not good, or if you are getting errors from ePubCheck or retailers that you just can’t figure out, consider having a professional eBook developer perform a diagnostic check on your ePub file.

Update 8/6/14: In addition to all of these points, you should always test your files in FlightDeck, our EPUB quality assurance testing tool. You’ll get reports about Validation, Best Practices, and Retailer Support, and more.

Those are just some of the things you can do to make sure your eBook files succeed, even on a small budget.

Why eBook Conversion is Complicated

Posted on

red-buttonIt is still surprising to many people that eBook development is a complicated process. The increase in the number of eBook creation tools over the last 3 years has led to many claims that eBook development is as easy (or should be as easy) as pressing a button.

Despite these claims, nothing could be further from the truth. Yes, there are many tools that can create eBook files, and sometimes these tools can do a decent job, especially for certain types of eBooks. However, when developing eBook files, there is a direct correlation between the amount of human interaction with the code and the quality of the final product.

So, why is this the case? What makes eBook development so complicated?

1. Formats. While many people will say that the ePub and Kindle formats are the same thing, there are still some differences between the two formats. The best practice is to create each format independently, not just auto-convert an ePub into the Kindle format with the KindleGen tool. While that does add time to the development of the eBook, it also increases the quality of the reader experience.

2. Reading Systems. If you look at any of the major eBook retailers you will see that they allow consumers to read eBooks on a variety of devices. For example, Amazon has the basic Kindle, Paperwhite, Fire, Fire HD, and Fire HDX, as well as apps for PC, Mac, Android, iOS, Windows Phone, and Blackberry. While retailers do try to create a seamless reading experience across devices, that is not always possible. The best eBook files will be designed to take the differences and quirks of each eBook device into consideration and attempt to be compatible with all of the reading systems that each retailer supports.

3. Display Engines. On a deeper technical level, every reading system, whether it is a device or an app, uses a display engine to translate the HTML code in the eBook file and display it on the screen. The most common display engines are Webkit and Adobe’s RMSDK, but there are also many variants of Webkit being used, as well as hacks and overrides imposed by each reading system. These display engines do not all work the same way, and you will regularly see both major and minor differences in how eBook content looks on devices that supposedly use the same display engine.

4. And more… Those major hurtles are not the only problem areas for eBook development. There are also the issues that come with fonts, images, tables, lists, and other more complex formatting, as well as enhancements and additional features that an author or publisher might want to include.

In all, designing an eBook is more difficult than just laying out the content in InDesign or Word, especially if you are looking for a consistent design across multiple devices and retailers. Its not going to get easier, either. The difficulties of eBook creation will actually increase with the coming support for ePub3; built-in accessibility, more focus on semantic markup and semantic inflection, better support for enhancements, and other new functionality will add both time and complexity to the eBook development process.

eBook quality matters, and customers will notice when an eBook is not designed well. It is always best to spend the extra time and energy up front to make a better eBook file than to fix an inferior product after your customers complain.

The Incrementor

Posted on

We use many open source tools in our day-to-day operations here at eBook Architects; tools like Gimp, Inkscape, Perl, and Python form integral parts of our process and allow us to keep our costs down. To say thanks, eBook Architects has been looking for ways to give back to the open source community, such as assisting in the launch of the #ePrdctn Wiki and by maintaining and spreading great tools like epub-applescripts and kindlegen-drop-app. We hope that these tools and resources are as useful in your eBook development as they are in ours.

The foundation of any good coding operation is the code editor you use. We recently switched to a code editor called Sublime Text 2, a cross-platform program with a dedicated developer, a consistent upgrade schedule, a large community of other users, and an impressively flexible and adjustable interface and feature set. There are a few things that our old editor allowed us to do that Sublime does not  have built-in, but we were able to code replacement functions in Sublime, keeping the developer learning curve during our switch-over down to a bare minimum.

Today we are releasing one of those new features, a  Sublime Text 2 plugin called The Incrementor, into the open source world! This little tool allows you to do common tasks like re-numbering the PlayOrder values in an NCX file quickly and easily. To download or learn more about The Incrementor visit our Github page.

Major kudos go to the coding team here at eBook Architects (TobyChris, and AJ) for their hard work on this Sublime switch over and the Incrementor plugin.

KindleGen 2.5 update

Posted on

Sorry for the long hiatus… Things are really busy here at eBA!

Just wanted to give my thoughts on the updates released in KindleGen 2.5 today. The release notes include more items, but these are the ones that are most important to me:

Improved transparent PNG conversion: Transparent PNG images (now converted to JPEG) will use white background. This originally used black background during conversion causing degraded reading experience.
While not an update to support transparent PNG, this is definitely an improvement from a development standpoint. Now at least we don’t have to create separate JPGs or flatten our PNGs when building Kindle files.

Resolved indentation issues in Mobi7 related to bullets and numbered lists. This was due to usage of “margin-left” CSS property with bullets and numbered lists. In Mobi7, the margin-left property is being ignored for bullets and numbered lists. The margin-left CSS property will continue to be preserved in KF8.
This has been a big issue for us when developing non-fiction Kindle files. Hopefully B&N follows suit and updates their system to allow lists with 10 or more elements…

CSS property display: none no longer induces an additional space in Mobi7 for inline tags.
Peter over at Extraordinary Commons should be even happy about this than I am.

Resolved conversion failure when dc:Language tag in OPF has attributes (ex: id attribute).
This has been annoying Toby for a while. We include IDs in all of our metadata attributes for ePub and Kindle OPF files.

Overall, this is a nice maintenance update. It is always great to see Amazon (and anyone else!) actively working on support for features and bugs that developers need. Keep on sending them suggestions!

Backwards Compatible Poetry for KF8/Mobi

Posted on

One of the most enjoyable, and at times most frustrating, things about eBook development is learning new systems and formats when they are released. The new Kindle Format 8 (KF8) comes with some great changes to the design capabilities on the Kindle platform, but one of the main challenges in using it is creating Kindle files that will degrade gracefully to the older Kindle devices that do not have support for KF8.

A prime example of formatting that needs backwards compatibility is poetry. In 2008 I developed the now-standard approach of using Mobipocket’s width attribute combined with specific values and non-breaking spaces to make poetry work well in Kindle devices. I covered that in detail in my book, Kindle Formatting: The Complete Guide.

In KF8, the old width attribute is no longer valid, so using this code for backwards compatibility is not possible. In the early beta versions of the KindleGen 2 tool for KF8, there was no way to make the hanging indents work properly in Mobi while still making a valid KF8 file, so I complained to Amazon about the need for a CSS-driven option using media queries. They came through with a small change to the final release version of KindleGen that allows the use of negative values in the text-indent CSS property.

So, here is a new way to create valid code in your KF8 files that will degrade gracefully for older Mobi-only devices.

The HTML is actually pretty simple. The class name designates a paragraph’s level of indentation. The non-breaking spaces are placed inside span tags that can be hidden in KF8.

<p class="poem1">Poem1. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
<p class="poem2"><span class="hide">&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;</span>Poem2. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
<p class="poem3"><span class="hide">&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;</span>Poem3. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
<p class="poem4"><span class="hide">&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;</span>Poem4. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
<p class="poem5"><span class="hide">&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;</span>Poem5. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
<p class="poem6"><span class="hide">&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;&#xa0;</span>Poem6. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>

The CSS starts off with the use of media queries. One section of the CSS is defining the styles for Mobipocket-only devices, and the other is defining the styles for other devices (those that support KF8 or another future format).

@media amzn-mobi {
p.poem1 {
text-align: left;
text-indent: -30px;
p.poem2 {
text-align: left;
text-indent: -60px;
p.poem3 {
text-align: left;
text-indent: -90px;
p.poem4 {
text-align: left;
text-indent: -120px;
p.poem5 {
text-align: left;
text-indent: -150px;
p.poem6 {
text-align: left;
text-indent: -180px;

@media not amzn-mobi {
p {
margin-top: 0;
margin-bottom: 0;
.hide {display: none;}
p.poem1 {
text-align: left;
text-indent: -30px;
margin-left: 30px;
p.poem2 {
text-align: left;
text-indent: -30px;
margin-left: 60px;
p.poem3 {
text-align: left;
text-indent: -30px;
margin-left: 90px;
p.poem4 {
text-align: left;
text-indent: -30px;
margin-left: 120px;
p.poem5 {
text-align: left;
text-indent: -30px;
margin-left: 150px;
p.poem6 {
text-align: left;
text-indent: -30px;
margin-left: 180px;

The Mobi-only CSS uses the negative text-indent to emulate the width attribute, and the KF8 CSS hides the non-breaking spaces and uses the standard CSS approach to hanging indents (negative text-indent, positive margin-left).

That’s it! Come back later for more posts on KF8 development and backwards compatibility.