Can Everton Jones find out how his father stole Emperor Bokassa’s diamonds and, more importantly, where he hid them; before the world and his brother get there first?
Click on the picture link in the sidebar to read an extract of my first novel, which was published by Paradise Press in August 2012.

Wednesday, 12 November 2014

How to test your e-pub using flightCrew in Sigil

Once you have a completed epub e-book, you need to test it.


If there are any errors, they are usually because of careless typing mistakes. After all, Sigil won’t let you close your file unless the html is syntactically correct. Unfortunately, this does NOT necessarily mean your html achieves what you intended! Sigil does its best to understand what you meant, but isn’t clairvoyant. If it mends your html it will produce valid html code, but this might not display as you want it to. Careful proofing is always necesary, and I strongly recommend against clicking the ‘correct automatically’ option which Sigil offers when it finds a mistake. Go back and find the mistake and correct it manually.

So I’m assuming you have already proofed your e-book and corrected the styling and made sure there are no obvious mistakes. For instance you will need to check that italic and boldface render correctly and that any links for indexes, footnotes etc. work properly.

One possible pitfall is if your <span> tags do not close properly. The <span> tag in html just identifies a section of the text and allows you to label or format it. I have used <span> tags for the labels which links jump to and also for italic and small caps. You might have an opening <span class="italicText">, or <span class="smallCaps"> or <span id="x3"> tag, for exampe. BUT the closing </span> tag looks the same for each. Both Sigil AND the e-reader will assume that a closing </span> tag closes the <span> which immediately preceeds it. IF your closing tags are in the wrong place the results will be unpredicatble. For instance:

<span class="italicText">an example of <span class="boldFace">a mistake</span> you might make</span>

will render like this:

an example of a mistake you might make.

In this example, the <span> tags overlap, generating bold and italic in the intersection.

Any error like this will NOT be picked up by Sigil. You will have to look for this or other similar errors and correct them manually. Hopefully, if you have placed the markup in the correct places and made the replacements in the correct sequence there should not be any errors of this type.

Once your file has been proofed, you will then need to use the built-in tools in Sigil, called ‘flightCrew’, to check it. To use them, just click the green ‘tick’ button in the toolbar:

The results of the validation are displayed at the bottom of the main Sigil window. Hopefully you will see this:

[added: 29 Oct. 2015: The new version of Sigil implements Flightcrew as a plugin, which you need to install and configure properly. I explain how to do this here.]

If there are errors, then you will need to track them down and correct them. Sigil will just report on what it finds, and ONE error frequently generates TWO error messages, which can be offputting. To generate some examples, I went back to a working e-pub and made a number of deliberate mistakes:

A file is NOT referenced:

For example you might have imported a new front cover image and forgot to delete the old one. To create a similar error, I loaded a new image: ‘KindleFront.jpg’ and just left it in the images folder without using it. Sigil reported this error:

‘File: OEBPS/Images/KindleFront.jpg: This resource is present in the OPF <manifest>, but it’s not reachable (it’s unused).’

This message tells you the problem is with the file: ‘KindleFront.jpg’ in the ‘Images’ folder. It says the file is listed in the manifest, but isn’t actually used. So delete the redundant file.

The error message is displayed with a yellow background, this means it is something you might want to deal with but won’t stop the e-pub from working. It’s best practice to deal with ALL errors, however. You want an e-book which has NO issues at all. Apple and other e-book resellers will run epubcheck and send your e-book back if there are any errors, however trivial, so that’s another reason for dealing with every single error, fatal or otherwise!

Mistyped name:

If, however, you imported an image but made a typing mistake when entering it on a page, a different error will be reported. I edited the page for the front cover to change the name of ‘ebookFront.jpg’ to ‘ebookFornt.jpg’ and ran flightCrew. I got TWO messages:

The first, in RED this time, is the most serious, and will stop the e-pub from working properly:

‘File:OEBPS/Images/ebookFornt.jpg: The resource is reachable but not present in the OPF <manifest>. "Reachable" means that a reference of some kind that points to this resource exists in the epub.’

It is saying you have referred to the image in the e-book, but the actual file isn’t listed in the manifest. (That would be right, because I deliberately mis-typed the name!) When the ebook reader tries to display the page it won’t be able to find the image and will just show a question mark or a blank space instead.

The second message:

‘File: OEBPS/Images/ebookFront.jpg: This resource is present in the OPF <manifest> but it’s not reachable (it’s unused).’

is essentially the same error as in the last example: The file: ‘ebookFront.jpg’ is there, and listed in the manifest but, because the name used in the html cover was mistyped, this file is not used.

To find the error, the easiest way would be to open all the files in the e-book in Sigil and then search for ‘ebookFornt.jpg’. You can then correct the typo.

Mistyped Link:

I then edited a link, which SHOULD have been to a file called ‘Monday.xhtml’ so it read ‘monday.xhtml’ (all names are case sensitive). This time TWO RED warnings were generated:

‘File: OEBPS/Text/monday.xhtml: This OPS document is reachable but not present in the OPF <spine>. "Reachable" means that a reference of some kind that points to this resource exists in the epub’


‘File: OEBPS/Text/monday.xhtml: This OPS document is reachable but not present in the OPF <manifest>. "Reachable" means that a reference of some kind that points to this resource exists in the epub.’

One error message says the file ‘monday.jpg’ isn’t in the spine and the second says it isn’t in the manifest. You will readily appreciate that a working knowledge of the structure of content.opf will be invaluable in understanding these error messages. (Refer to my posts on content.opf for further information.) Clicking the mis-typed link will not work because the file it links to doesn’t exist. Look in the manifest to find out the correct spelling of the file, search the e-book for the incorrect name and then correct it.

Note also that the filenames and everything else are case sensitive. A casual glance at your files can miss a capitalisation error such as the one in this example.

Duplicate labels:

You may recall I keep banging on that all labels used in your e-book must be unique (i.e. each one should be different). Well, I went back to the file ‘Tuesday.xhtml’ and changed a label from id="tuesdayMorning" to id="tuesdayAfternoon". This meant there were TWO identical labels (tuesdayAfternoon) in the same file. Running flightCrew generated TWO errors:

‘File: OEBPS/toc.ncx: Line: 60: This <content> element’s "src" attribute value is "Text/Tuesday.xhtml#tuesdayMorning", but an element with an ID the fragment is referring to does not exist in that file.’


‘File: OEBPS/Text/Tuesday.xhtml: Line: 100 ID value 'tuesdayAfternoon' is not unique.’

THIS time Sigil has helpfully provided line numbers. Double-clicking the error now takes you directly to the relevant place in the file, which is a really useful feature. The first error message is a bit scary, but is just because the logical table of contents refers to a label (or id) which no longer exists. The second message is much more straightforward and simply identifies that the label is not unique. The line reference is to the SECOND instance of the duplicate label in the file. Sigil has no idea which of the two labels is mis-typed: it can’t read your mind! All it knows is that it found the first label and then another, identical, label, which is the one it flags up as an error. In actual fact the typo I created was in the FIRST label, so you would still need to search for that in order to edit it. Correcting the label will deal with BOTH error messages. As a general rule, if you deal with the most obvious error messages first, some of the more obscure-looking ones will most likely go away by themselves.

Invalid Label:

You will recall I also keep saying to use labels and filenames which are single text strings with NO SPACES. Well, I put a space in the label for ‘tuesday Morning’, and got the following errors:

‘File: OEBPS/toc.ncx Line: 60: This <content> element’s "src" attribute value is "Text/Tuesday.xhtml#tuesdayMorning", but an element with an ID the fragment is referring to does not exist in that file.’


‘File: OEBPS/Text/Tuesday.xhtml Line: 20 value 'tuesday Morning' is invalid NCName.’

The last one is the most informative. Seeing this you would edit the label to remove the space and everything would be alright. (Although you would need to check it was correct elsewhere as well, after all, the label is there for a reason, in this case as the target of a link in the html table of contents. There will be knock-on effects you may need to deal with in a real file.) The first error message is just because the logical table of contents refers to a label which doesn’t exist (I just edited it, remember!).

Order of the error messages:

Unfortunately, the error messages will be displayed in the order in which they arise when Sigil goes through the file. They will NOT be conveniently paired up as they are above. You might need to go through the error messages several times, dealing with the most obvious ones first, before you have nailed them all.

Next Steps: Once you have an epub which passes flightCrew in Sigil, you are ready to check it with epubcheck, which is the industry-standard error-checking program. My next post will cover how to download and use epubcheck to validate your e-pub.

Index to ‘how to …’ posts:

How to ‘unpack’ an epub file to edit the contents and see what’s inside.
How to understand what is inside an epub
How to link the html table of Contents in a Kindle e-book
How to restructure the html table of contents for a Kindle
How to delete the html cover for a Kindle ebook
How to link the cover IMAGE in a Kindle e-book
How to clean up your MS Word file before your get started
How to markup an MS Word file to identify the formats before importing it into an epub
How to create a new blank e-pub using Sigil
How to import your marked-up MS Word file into your ebook using Sigil
How to create and link a CSS stylesheet in an e-book using Sigil
How to replace the markup with CSS styles in your ebook using Sigil
How to style an e-book so it works with the limited CSS styling available to Kindle e-readers
How to understand the syntax of CSS
How to style Small Caps in an e-book
How to split your ebook up into chapters using Sigil
How to sequence your e-book
How to phrase the copyright declarations etc. in an e-book
How to generate the logical table of contents using Sigil
How to understand toc.ncx in an e-book
How to generate the html table of contents in an e-pub
How to style the html table of contents using CSS
How to create an html cover for your epub using Sigil
How to present references and notes in a book
How to use Mark Up to link notes in your e-book
How to present a bibliography in a book
How to use markup to link entries in a bibliography with the notes section
How to index an e-book
How to use the tools in MS Word to create an index
How to alphabetise an index or bibliography
How to adapt the print index in your MS Word file for an e-book using markup
How to adapt cross-references in your print index for e-book and how to use markup to make the links
How to understand content.opf
How to understand and edit the Metadata of an ebook using Sigil
How to understand the manifest in content.opf
How to understand the spine and guide in content.opf
How to test your e-pub using flightCrew in Sigil

TinyURL for this post:

No comments:

Post a Comment

Twitter Bird Gadget