Lognormality > ePubCheck Helper

07 September 2013 | | categories: projects, software | blog archive

Kobo eReader by Neil Harvey photo credit: Neil Harvey

-[ background ]-

ePubCheck is a great command line utility that validates EPUB files to ensure proper structure and formatting.  It provides a detailed log of issues, including improper html tags, indicating which row(s) of which file(s) in the EPUB contain the errors.  It is an invaluable resource when creating EPUB files.

ePubCheck Helper is a simple batch file that allows the user to drag and drop an EPUB file (or a .zip file, as .epub files are renamed .zip files) to run ePubCheck, taking care of the command line details for you.  The script outputs ePubCheck’s log to a .txt file in the directory with the original EPUB file.

-[ notes ]-

I know this isn’t the first utility of its kind (for instance, EPUB-CHECKER seems to be a good one and there is also the web-based EPUB validator), and it likely isn’t the best.  I wanted to learn more about batch scripting and this seemed like a good way to do so.  The results might be helpful for someone.

I am by no means an expert at batch scripting.  I welcome comments on this script.

-[ requirements/limitations ]-

  • The user must have ePubCheck installed.
  • This assumes the user is running Windows (checked with Windows 7, may work with earlier/later versions).

    • The date/time stamp on the log filename only works properly for users whose Windows installation uses US-formatted dates (MM-DD-YYYY).

-[ instructions ]-


  1. Make sure you are running java (1.6 or above).  This is a requirement of ePubCheck.
  2. Install ePubCheck.  The latest version (as of 2013-09-07) is 3.0.1, but this should work with other versions.
  3. Download the .zip file (epc-helper.zip).
  4. Extract the .bat file (epc-helper.bat) to the same folder where you have previously installed ePubCheck.

Running ePubCheck Helper:

  1. Create a shortcut to epc-helper.bat in the folder where your EPUB file(s) is (are) located.
  2. Drag and drop an EPUB file onto the shortcut you created in step 1.  This runs ePubCheck.
    • The script checks for a .epub extension.
    • Dragging and dropping a file with a .zip extension also works.
      • In this case, the script copies the .zip file to a new file with the same filename and an extension of .epub.  (This can help save time, as it automates the required renaming step in EPUB creation.)
    • Dragging and dropping files with any extension other than .epub or .zip terminates the script.
  3. When ePubCheck has finished, a pop-up window will tell you the status.
    • Successful completion:  the filename of the log file where the results are stored is displayed (“Successful” in this case refers to ePubCheck running successfully, not to successful validation of the .epub file itself)
    • Unsuccessful completion:  you attempted to run ePubCheck on a file with the wrong extension (not .epub or .zip)
    • Unsuccessful completion:  ePubCheck cannot be found in the same folder where epc-helper.bat is located.  If you receive this message, make sure you followed the instructions above (under “installation”) and try again.
  4. Check the log file for errors.  The log file’s name will be [EPUB name]-[date/time stamp].log.
    • The date/time stamp is added so you can easily keep track of which validation attempt you are looking at.
    • Date/time stamp format:  YYYYMMDD-HH_MM_SS
    • Example:  epub-20130907-17_46_31.log
  5. Fix the errors in your EPUB (as noted in the log file) and try again (go to step 2) if necessary.  If your EPUB file successfully validates, congratulations!

-[ to do ]-

  • Make the time stamp work with systems having non-US formatted dates

-[ acknowledgment ]-

-[ license ]-

-[ changelog ]-

0.1.0-a (2015-01-19)

  • moving files to GitHub

0.1.0 (2013-09-07)

  • first release

-[ download ]-

[ batch file + documentation ] | [ all files ] | [ .zip (v.0.1.0) ]