Epubgen: Creating epub files from Elsevier dataset

From STMDocs
Jump to: navigation, search

What is epubgen?

epubgen is a tool for generating ePub files from Elsevier's Journal and Book (Stand-alone and Book-Series) CONTRAST-out datasets. epubgen is created as a command line interface (CLI) tool. This tool is compatible with both Linux and Windows platforms. The input is Elsevier's CONTRAST-OUT dataset and the output is the epub file. A dataset is actually an archive (in other terms a container of files). This archive may contain, the PDF, XML, stripins (gif images of MathML code), figures and a dataset.xml. dataset.xml is the entry point to the dataset which contains the details including path names of the files in the dataset.

This program is released under the GNU General Public License.


  1. A single dataset may contain a collection of issues or books. By default each issue/book will be separate ePub file. But if epub files of each item (ie, article/book) is needed, then you can split the files.
  2. In the XML file, both MathML code and as an alternative, stripins (images of MathML code) are available. This program is now set in such a way that you can select to render MathML or view the images or SVG or all of them.
  3. You can select the level of the table of contents using the command line switch. Default is 3.
  4. This tool will work both in Linux and Windows Platforms.

Software dependencies

  1. epubcheck (version 1.0.4 or higher) which is a parser for epub files.
  2. Perl 5.8.8 or higher
  3. xsltproc
  4. saxon (ver. 9 or higher)
  5. xmllint
  6. convert (ImageMagick 6.3.7 or higher)
  7. zip. The ePub file is actually a zip file with extension .epub.
  8. Java 1.6 or higher.
  9. Cygwin is required for Windows.


The installation is so simple that you just need to unzip the archive. All the files will be extracted to a folder named epubgen-*.* which will be called `installation path' from now onwards. *.* stands for the correct version number which you see in the folder you get when you unzip the archive. This folder contains epubgen.pl, epubgen.sh, epubgen.bat, epubgen.conf etc. If you add the installation path to the system variable PATH, that will be the more efficient way of working.

Firstly, edit the epub.conf file to set the path of Java. Even if Java path is set properly in your system variables, setting this path in epub.conf is also necessary. For both Linux and Windows, seperate variables are given. If you are a Linux user, then set the variable for Linux and comment out the variable for Windows and vice versa.

How to create epub files?

Unzip the CONTRAST-OUT dataset to any folder and use the following syntax:



epubgen.sh -d [Options] [name of folder where dataset.xml resides] \
 -p [folder where epub file should be generated]


epubgen.sh -d /opt/my-dataset/EWX00001158/ -p /opt/my-epub-files/

There is difference in the usage of commands for Cygwin terminal and default command line terminal. In the following syntax, the first one is for Cygwin terminal and the other is for default command line terminal:


epubgen.sh -d [Options] [name of folder where dataset.xml resides] 
 -p [folder where epub file should be generated]
epubgen.pl -d [Options] [name of folder where dataset.xml resides] 
 -p [folder where epub file should be generated]


epubgen.sh -d e:/my-dataset/EWX00001158/  -p  e:/my-epub-files/
epubgen.pl -d e:\my-dataset\EWX00001158  -p  e:\my-epub-files\

List of options

--valid or -v         Validate the epub file produced. Default is to validate

--path or -p          Path to which epub files are to be copied

--nostripins or -S    Not to include stripins. Default is to include stripins

--svg or -g           [yes|no] Whether to insert SVG code for math
--mathml or -m        [yes|no] Whether to retain mathml code. 
                      Default is no. Either stripins or mathml is required however

--item or -i          To split epub files item wise. Default is single epub for single issue

--level or -l         Level of table of contents to be included in the toc.ncx file of epub. Default is 3

Project home page

This project is hosted in gna.org. The URL is:


To get the information about how to access the source code repository, please visit the following URL:


How to contact

Suggestions, recommendations, feature requests, bug reports, etc can be send to Support. Bugs can also be filed at the Bugtracker, but you need to login at http://gna.org.