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, 19 November 2014

How to test your e-book using epubcheck

You will need to test your e-book against the industry-standard epub validation program, called epubcheck. You may well have checked it already using the tools in Sigil, called flightCrew, and that will have caught most errors. (See my post on using flightCrew to test your e-book.) And I would definitely advise you to do this first. But epubcheck is a more stringent test and may well throw up errors which flightCrew might have let through. More importantly, Apple and other resellers will run your e-pub through epubcheck and return it if there is a single error, so save yourself some heartache and make sure your e-book WILL pass.


There ARE some handy versions of epubcheck which allow you just to drag and drop the epub file onto an icon and then run it by epubcheck. BUT these are made by third parties and often do not implement the latest version of epubcheck. It is better to get the pucker, latest, official, incarnation of epubcheck directly from IDPF and then you can be sure you have a valid e-book.

How to get epubcheck:

The places to download software from can change, and versions update from time to time. At the time of writing, the current version of epubcheck is 3.0.1 and can be downloaded from here: https://github.com/IDPF/epubcheck/releases/tag/v3.0.1. If that link does not work, you might try: https://github.com/idpf/epubcheck from where you should be able to find a link to the latest official download site. The first link took me to a page from where I found the download link for epubcheck-3.0.1.zip, which I clicked and saved the file to my desktop (strongly recommended).

[update 14 August 2017: follow the second link above and find the latest version: v4.0.2 which fixes an important security vulnerability.]

Once you have the .zip file, you should extract it by right-clicking on the icon and selecting ‘extract all …’ from the pop-up menu. Select the desktop as the destination of the file from the dialog and click the ‘extract’ button (Windows). If you have a Mac, just double-click on the .zip file and it should extract itself automatically. For some reason, I ended up with a folder called epubcheck-3.0.1 containing another folder with the same name:




So I dragged the inner folder to the desktop. You may need to use a different method, depending on your operating system. What you want is ONE folder on the desktop containing these files:


How to get Java:

The important file is the one called epubcheck-3.0.1.jar, which, unfortunately, is a java program. To run it, you will need the latest version of the java runtime environment installed on your computer. This can also be confusing, but the simplest way to get java would be to go to this website: http://java.com/en/download/installed.jsp from where you can check whether you have the latest version on your computer and download/update it.

But you are not yet done. Epubcheck, like kindlegen is a command-line program, and to use it you will need to find and run the command prompt interface (Windows) or the Terminal (Mac). This is inconvenient, and will take many of us out of our comfort zone, but is unfortunately unavoidable.

Finding the Command Prompt (Windows):

Perhaps the simplest way to find the command prompt in Windows is from the start menu. Just enter ‘Command Prompt’ in the search box:


and the command prompt should make an appearance in the list of results (you want the one with the black ‘ C:\_ ’ icon, at the top of the list below):


And now right-click on the icon and select ‘pin to taskbar’ from the pop-up menu:


You should then be able to access the command prompt from the taskbar at any time. Or you might want to make an alias for your desktop, which in Windows 7 can be done by selecting ‘Send to ▶ Desktop (create shortcut)’ from the pop-up:



Whether it is an alias or on the taskbar, or even directly in the start menu, just double-click the icon to launch it.

I will cover how to use the terminal to run epubcheck on a Mac at the end of this post.

Running epubcheck from the command prompt in Windows:

Open the command prompt in Windows:


You can now type instructions into the window. Be careful, as blundering around without knowing what you are doing can have catastrophic results for your computer. A brief search unearthed this resource: www.makeuseof.com/tag/a-beginners-guide-to-the-windows-command-line/ which may be helpful if you are curious about how to do stuff using the command prompt. However this post is concerned only with how to use it to run epubcheck. To do this you first need to invoke Java:

To invoke java, type: ‘ java -jar _ ’ (followed by a space: it should look as it is pictured inside the quotes) into the command-prompt window (don’t hit return at this point!):


To make your life easier, open the epubcheck-3.0.1 folder and drag it somewhere close to the command prompt window. Now DRAG the icon for epubcheck-3.0.1.jar onto the command prompt window:


This should copy the filename and path into the command line interface:


The window should say:

C:\Users\Rod>java -jar C:\Users\Rod\Desktop\epubcheck-3.0.1\epubcheck-3.0.1.jar_

Type another space at the end:

C:\Users\Rod>java -jar C:\Users\Rod\Desktop\epubcheck-3.0.1\epubcheck-3.0.1.jar _

and then drag the icon for the epub file you want to check onto the window in exactly the same way. The filename and path should be copied, exactly as before. The window should now contain this:

C:\Users\Rod>java -jar C:\Users\Rod\Desktop\epubcheck-3.0.1\epubcheck-3.0.1.jar C:\Users\Rod\Desktop\Example.epub_

Now you have built the whole command, you can hit return, which runs epubcheck and, hopefully, will display the following (you may have to wait a bit to get the results!):

Epubcheck Version 3.0.1

Validating against EPUB version 2.0
No errors of warnings detected.

C:\Users\Rod>_

The C:\ prompt returns once the program has completed. You can use the up and down arrow keys to cycle through commands you have issued, which could come in very handy if you end up testing the same file over and over again!

If you DO find yourself running epubcheck over and over again, it will probably be because you keep getting errors. In which case you may want to save the errors to a file rather than displaying them in the command prompt window, particularly if there are a lot of them! After a bit of googling around I found a way to do this:

Saving the output from epubcheck to a file:

To save the output from epubcheck to a file, you first need to change the directory to wherever you want the output file to go. The command prompt in the examples begins with  ‘ C:\Users\Rod>_ ’, which is my root directory. The desktop is in this directory, so if I type: ‘ cd Desktop ’after the command prompt, it will change to: ‘ C:\Users\Rod\Desktop>_ ’. To direct the output to a file on the desktop, type the following (the spaces matter):

C:\Users\Rod\Desktop>java -jar C:\Users\Rod\Desktop\epubcheck-3.0.1\epubcheck-3.0.1.jar Example.epub >output.txt 2>&1_

Hit return and a file called output.txt will be created on the desktop containing the output from epubcheck. (You can substitute any other filename you want.) It is a good discipline to routinely save each set of error messages in separate files for reference.

Perhaps I ought to add that to change the drive, you need to type the drive letter: ‘ C:\Users\Rod> E:_ ’ for example, changes to the E: drive: ‘ E:>_ ’, from where you can specify a directory on the E: drive for the output to go to. For example: ‘ E:>cd ebooks\myEbook_ ’ would change the working directory to E:\ebooks\myEbook, and the command prompt will chage to: ‘ E:\ebooks\myEbook>_ ’.(Obviously, you can specify any drive which exists: I use removable media for all my files, to keep my data safe should my operating system break. My ‘E:’ drive is the SD card reader.)

Bear in mind, though, that nothing whatever will be displayed in the window whilst the program is executing, because the output is being diverted to the file you specified. The only indication you will have that the program has completed and your output is ready to look at will be when the command prompt returns.

The results from epubcheck:

In my case, the epub file I used was an epub 2.0 e-book and epubcheck detected this (the version number is embedded in the e-book in the opening <package > tag in content.opf) and validated it against the appropriate specification. Epubcheck 3.0.1 will be able to validate epub 2.0 or epub 3.0 e-books.

To create an error, I went back to the e-book and put spaces into a filename. Running epubcheck again produced this error message:

Epubcheck Version 3.0.1

Validating against EPUB version 2.0
WARNING: C:/Users/Rod/Desktop/Example.epub/OEBPS/Text/A Visitor's Guide to Bexhill.xhtml: Filename contains spaces. Consider changing filename such that URI escaping is not necessary

Check finished with warnings or errors

Errors like this are a bugger, because there may well be knock-on consequences of changing the filename. Sigil may well take care of them for you, like updating content.opf, but you would be well advised to check that things like links in the html table of contents etc. are also updated. Heaven help you if you have an index!!!! Find and replace may well come to your rescue!!

Once the error has been put right, you will need to run epubcheck again, correct any errors which are still there or indeed any new ones which your ‘correction’ might have generated (!) and then run epubcheck again until all errors have been eliminated.

And then you have a finished e-pub!!

Running epubcheck from the terminal on a Mac:

Firstly, download epubcheck and save the folder to the desktop, as outlined above for Windows. And also check you have the current version of the java runtime environment installed.

The Terminal is the command-line interface on the Mac, and is directly analogous to the command prompt on a Windows computer. In fact, the Terminal betrays the fact that OsX is essentially a kind of linux environment. Most of the commands you can issue via the terminal are the same as in linux. You can get a handy guide to using the terminal interface here: http://guides.macrumors.com/Terminal. As I said about the Windows command prompt, be careful what you type in here, be sure you know what you are doing! Fortunately, running epubcheck is a simple matter!

To get to the terminal, locate it in the utilities folder inside the applications folder and drag it to the dock from where you can access it more easily. Or indeed make an alias and put it on the desktop.

When you open the Terminal, you will get a window like this (top LH portion):


As described above for Windows, you should invoke java by typing ‘java -jar ’ (followed by a space: it should look as it is pictured inside the quotes). Then open the epubcheck folder and locate it close to the Terminal window. Now click and drag the epubcheck icon onto the Terminal window:


In this case, the path to epubcheck was copied including a space at the end:

 Johns-iMac:~ johnkeithshelton$ java -jar users/johnkeithshelton/desktop/epubcheck-3.0.1/epubcheck-3.0.1.jar ▯ 

If for some reason you did not get a space, you would need to type one, as shown in the Windows example. Each component of the instruction needs to be separated from the others by a single space.

Now repeat the procedure with your epub file:



The Terminal window should now contain the fully assembled command (the paths to the various files would depend on where YOU had stored them but should copy correctly if the icon is dragged onto the Terminal window):

 Johns-iMac:~ johnkeithshelton$ java -jar users/johnkeithshelton/desktop/epubcheck-3.0.1/epubcheck-3.0.1.jar Volumes/PARADISEPRE/exampleEbook.epub▯ 

Hit return to run epubcheck and you will get the results. In this case, the outcome was the same as for the Windows example.

To get a copy of the error messages, your life is made easier on a Mac, as you can click and drag to select the messages, copy to the clipboard and then paste them into a blank MS Word file. Alternatively there is a handy reference here: www.maclife.com/article/columns/terminal_101_piping_output on how to direct the output from the Terminal to a file. In essence, this says to add:   > fiename.txt  after the command to write the output to the file: filename.txt instead of the screen. (note the space before and after ‘>’ compared with just a space before in Windows).

Next Steps: Now your e-pub is complete and passes epubcheck you can send it off to resellers such as Apple or Kobo or your wholesaler or upload it to your website for download. I have already covered the necessary steps you need to take to convert your e-pub to kindle. My next post will link to these posts and cover how to download and run kindlegen to make your kindle e-book.

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
How to test your e-pub using epubcheck
How to convert an e-pub to Kindle using kindlegen

TinyURL for this post:

No comments:

Post a Comment

 
Twitter Bird Gadget