epubtools

Library to convert and check EPUB 2 and 3

Repository
Git URLhttps://github.com/transpect/epubtools.git
SVN URLhttps://github.com/transpect/epubtools
Base URIhttp://transpect.io/epubtools/

Source ⬇

epub:create-ocf

This step is used to create the directory structure of the OCF Abstract Container. It is required to provide as option the path to the source html file.

Import

<p:import href="http://transpect.io/epubtools/modules/create-ocf/xpl/create-ocf.xpl"/>

Synopsis

<epub:create-ocf xmlns:epub="http://transpect.io/epubtools">
  <p:input port="meta"/>
  <p:output port="result" sequence="true" primary="true"/>
  <p:output port="files" primary="false"/>
  <p:option name="base-uri" required="true"/>
  <p:option name="debug" select="'no'"/>
  <p:option name="debug-dir-uri" select="'debug'"/>
</epub:create-ocf>

epub:create-opf

This step expects a file list of the EPUB content files in this form: <cx:document> <c:file name="OEBPS/chapter01.xhtml"/> </cx:document> It provides the OPF file on the result port. The output of the files port is the file reference of the content.opf but not all file references in the OPF file.

Import

<p:import href="http://transpect.io/epubtools/modules/create-opf/xpl/create-opf.xpl"/>

Dependencies

Synopsis

<epub:create-opf xmlns:epub="http://transpect.io/epubtools">
  <p:input port="source"/>
  <p:input port="meta"/>
  <p:output port="result" primary="true"/>
  <p:output port="files" primary="false"/>
  <p:option name="base-uri" required="true"/>
  <p:option name="target" select="'EPUB2'"/>
  <p:option name="terminate-on-error" select="'yes'"/>
  <p:option name="use-svg" select="'yes'"/>
  <p:option name="debug" select="'no'"/>
  <p:option name="debug-dir-uri" select="'debug'"/>
</epub:create-opf>

epub:create-ops

Hashed file names are patched into the HTML before split

Import

<p:import href="http://transpect.io/epubtools/modules/create-ops/xpl/create-ops.xpl"/>

Dependencies

Synopsis

<epub:create-ops xmlns:epub="http://transpect.io/epubtools">
  <p:input port="source" primary="true"/>
  <p:input port="conf" sequence="true" primary="false"/>
  <p:input port="meta" primary="false"/>
  <p:output port="result" primary="true"/>
  <p:output port="html"/>
  <p:output port="files" primary="false"/>
  <p:output port="report" sequence="true" primary="false"/>
  <p:output port="splitting-report" sequence="true"/>
  <p:option name="base-uri" required="true"/>
  <p:option name="target" select="'EPUB2'"/>
  <p:option name="css-filename" required="false" select="'stylesheet.css'"/>
  <p:option name="use-svg" select="'yes'"/>
  <p:option name="terminate-on-error" required="false" select="'yes'"/>
  <p:option name="debug" required="false" select="'no'"/>
  <p:option name="debug-dir-uri" required="false" select="'debug'"/>
  <p:option name="create-font-subset" required="false" select="'false'"/>
</epub:create-ops>

tr:create-font-subset

This pipeline can be used to create fontsubsets. The characters used in each font will be displayed in a character set. The subset is created using the pyftsubset phython script from fonttools https://github.com/fonttools

Import

<p:import href="http://transpect.io/epubtools/modules/fontsubsetter/xpl/fontsubsetter.xpl"/>

Dependencies

Synopsis

<tr:create-font-subset xmlns:tr="http://transpect.io">
  <p:input port="source" primary="true"/>
  <p:input port="expand-css"/>
  <p:output port="result" sequence="true" primary="true"/>
  <p:option name="debug" required="false" select="'yes'"/>
  <p:option name="debug-dir-uri" select="'debug'"/>
</tr:create-font-subset>

epub:html-splitter

Sample invocation (for debugging purposes):

calabash/calabash.sh 
    -i source=file:/$(cygpath -ma ../content/output/debug/epubtools/create-ops/pre-split.html) 
    -i conf=file:/$(cygpath -ma a9s/publisher/series/epubtools/heading-conf.xml) 
    -o result=tmp.html -o report=report.xml -o files=files.xml  
    file:/$(cygpath -ma epubtools/modules/html-splitter/xpl/html-splitter.xpl) 
    base-uri=file:/$(cygpath -ma ../content/output/debug/epubtools/create-ops/pre-split.html)
    debug=yes
    debug-dir-uri=file:/$(cygpath -ma ../content/output/debug)

Calabash seems to suppress some XSLT errors, for instance when a stylesheet is looping. Therefore it might be necessary to replace collection()[…] with document(…) in the XSL (alternative variable declarations are already included in the xsl file, commented out) and run saxon from the command line, for example like this:

PRE_SPLIT=file:/$(cygpath -ma ../content/le-tex/whitepaper/de/output/output/debug/epubtools/create-ops/pre-split.html)
saxon -xsl:epubtools/modules/html-splitter/xsl/html-splitter.xsl -s:$PRE_SPLIT -it:main \
    debug-dir-uri=file:/$(cygpath -ma debug) \
    debug=yes \
    final-pub-type=EPUB2 \
    heading-conf-uri=file:/$(cygpath -ma a9s/common/epubtools/heading-conf.xml) \
    meta-uri=file:/$(cygpath -ma ../content/le-tex/whitepaper/de/output/output/debug/epubtools/epub-config.xml) \
    datadir=file:/$(cygpath -ma debug/datadir)

Import

<p:import href="http://transpect.io/epubtools/modules/html-splitter/xpl/html-splitter.xpl"/>

Dependencies

Synopsis

<epub:html-splitter xmlns:epub="http://transpect.io/epubtools">
  <p:input port="source" primary="true"/>
  <p:input port="conf" sequence="true" primary="false"/>
  <p:input port="meta" primary="false"/>
  <p:input port="css-xml"/>
  <p:output port="result" primary="true"/>
  <p:output port="files" primary="false"/>
  <p:output port="report"/>
  <p:output port="unused-css-resources" sequence="true"/>
  <p:output port="splitting-report" sequence="true"/>
  <p:option name="base-uri" required="true"/>
  <p:option name="target" select="'EPUB2'"/>
  <p:option name="debug" select="'no'"/>
  <p:option name="debug-dir-uri" select="'debug'"/>
</epub:html-splitter>

epub:insert-amzn-region-magnification

This pipeline adds Amazon's Region Magnification markup to each div which includes the magnification class:

<div class="magnification">
  <p id="p-1-02">A quick brown fox jumps over a lazy dog.</p>
</div>

The script adds Region Magnification markup according to Amazon's Kindle Publishing Guidelines.

<div id="amzn-id-myBook-1-txt" class="source-mag"><a class="app-amzn-magnify" data-app-amzn-magnify="{"targetId":"magTarget-amzn-id-myBook\
      _000019-1","sourceId":"magSource-amzn-id-myBook-1","ordinal":1}">
  <p id="p-1-02">A quick brown fox jumps over a lazy dog.</p>
</a></div><div id="amzn-id-myBook-1-magTarget" class="target-mag">
  <p>A quick brown fox jumps over a lazy dog.</p>
</div>

Please note that you later need to execute a bash script which escapes the quotes. The script can be found here: scripts/escape-for-amzn-region-magnification.sh

Import

<p:import href="http://transpect.io/epubtools/modules/html-splitter/xpl/insert-amzn-region-magnification.xpl"/>

Synopsis

<epub:insert-amzn-region-magnification xmlns:epub="http://transpect.io/epubtools">
  <p:input port="source" sequence="true"/>
  <p:output port="result" sequence="true"/>
  <p:option name="amzn-region-magnification" select="'false'"/>
  <p:option name="debug" select="'no'"/>
  <p:option name="debug-dir-uri" select="'debug'"/>
</epub:insert-amzn-region-magnification>

epub:split-css

This pipeline is used to split the CSS based on the submitted value of the option css-handling. With the value regenerated-per-split, the CSS is analyzed and splitted for each HTML chunk. Commonly used CSS properties are stored to a global CSS stylesheet, whereas unused CSS properties are filtered. With the value unchanged CSS and HTML remain unchanged. Per default, a new CSS stylesheet is generated from the CSS XML representation.

Import

<p:import href="http://transpect.io/epubtools/modules/html-splitter/xpl/split-css.xpl"/>

Dependencies

Synopsis

<epub:split-css xmlns:epub="http://transpect.io/epubtools">
  <p:input port="source" sequence="true" primary="true"/>
  <p:input port="css-xml" primary="false"/>
  <p:output port="result" sequence="true" primary="true"/>
  <p:output port="unused-css-resources" sequence="true" primary="false"/>
  <p:option name="target" required="true"/>
  <p:option name="css-handling" required="true"/>
  <p:option name="basename" required="true"/>
  <p:option name="html-subdir-name" required="true"/>
  <p:option name="common-source-dir-elimination-regex" required="true"/>
  <p:option name="debug" select="'no'"/>
  <p:option name="debug-dir-uri" select="'debug'"/>
</epub:split-css>

epub:zip-package

This step expects a file manifest as input and creates a zip-package. The file manifest should have been this form:

Import

<p:import href="http://transpect.io/epubtools/modules/zip-package/xpl/zip-package.xpl"/>

Dependencies

Synopsis

<epub:zip-package xmlns:epub="http://transpect.io/epubtools">
  <p:input port="ocf-filerefs"/>
  <p:input port="opf-fileref"/>
  <p:input port="ops-filerefs"/>
  <p:input port="meta"/>
  <p:output port="result" primary="true"/>
  <p:output port="files" primary="false"/>
  <p:option name="base-uri" required="true"/>
  <p:option name="debug" select="'no'"/>
  <p:option name="debug-dir-uri" select="'debug'"/>
</epub:zip-package>

epub:convert

This step takes a HTML file as input and converts it to an epub file. You need a configuration for the HTML splitting and the OPF metadata. Examples can be found in the sample directory. Invoke this step on the command line with:

calabash/calabash.sh -i source=sample/b978-3-646-92351-3.xhtml 
  -i conf=sample/hierarchy.xml -i meta=sample/epub-config.xml epub-convert.xpl 

Note that it’s advisable to make all file inputs absolute URIs, by using cygpath on Cygwin or readlink -f on Unixy systems. For bash, this is, e.g., source=file:/$(cygpath -ma sample/b978-3-646-92351-3.xhtml)

Import

<p:import href="http://transpect.io/epubtools/xpl/epub-convert.xpl"/>

Dependencies

Synopsis

<epub:convert xmlns:epub="http://transpect.io/epubtools">
  <p:input port="source" primary="true"/>
  <p:input port="conf" sequence="true" primary="false"/>
  <p:input port="meta" primary="false"/>
  <p:input port="schematron"/>
  <p:input port="custom-schematron" sequence="true"/>
  <p:output port="result" primary="true"/>
  <p:output port="chunks" primary="false"/>
  <p:output port="opf" primary="false"/>
  <p:output port="files" primary="false"/>
  <p:output port="report" sequence="true" primary="false"/>
  <p:output port="html"/>
  <p:output port="baseuri" primary="false"/>
  <p:output port="input-for-schematron" primary="false"/>
  <p:option name="target" select="''"/>
  <p:option name="terminate-on-error" select="'yes'"/>
  <p:option name="clean-target-dir" select="'no'"/>
  <p:option name="debug" select="'no'"/>
  <p:option name="use-svg" required="false" select="''"/>
  <p:option name="debug-dir-uri" select="'debug'"/>
  <p:option name="status-dir-uri" select="'status'"/>
  <p:option name="id-in-report-heading" select="'false'"/>
  <p:option name="create-font-subset" required="false" select="'false'"/>
</epub:convert>

GitHub sync date: 2017-07-06+02:00