Chapter 9. The ebookc command-line utility

Command-line usage

ebookc [option]* in_ebook_file out_file_or_directory

Converts specified ebook input file and saves the result of the conversion to specified output file or directory.

An ebook input file may be specified using its URL or its filename.

Output formats webhelp, html and frameset require output_file_or_directory to be a directory. Other output formats require output_file_or_directory to be a file.

The output directory is created if it does not already exist.

Example: convert userguide.ebook to Web Help:

C:\docsrc> ebookc -f webhelp userguide.ebook out\wh

Example: convert userguide.ebook to PDF using RenderX XEP:

C:\docsrc> ebookc -xep C:\xep\xep.bat userguide.ebook out\userguide.pdf

Commonly used command-line options

Some options have both a short name and a long name. Example: -p is equivalent to -param.

-p param_name param_value
-param param_name param_value
Specifies a conversion parameter, generally an XSLT stylesheet parameter.
"profile." parameters

A param_name starting with "profile." specifies a profiling attribute. Example: -p profile.data-output-format html or more simply -p profile.output-format html (the "data-" attribute name prefix being implied). See Section 4.2. Conditional processing.

"proc." parameters

A param_name starting with "proc." specifies a low-level option which is passed to the first pass of ebookc. This first pass, called the Processor, compiles the input ebook specification to multi-page XHTML5 with a frameset and a “TOC frame”[1], see Chapter 8. How it works. Example: -p proc.resourcedirname resources.

Setting these low-level options “by hand” is almost never needed, it's best not to fiddle with these.

Table 9-1. Low-level processor options
Option Value Description

debug

true | false

Default: false.

Print low-level debugging info.

externalresourcebase

Absolute or relative URI ending with '/'.

Default: '' (no base).

Specifies an absolute or relative URI to be prepended to external resources having a relative URI.

framesetfilename

File basename without any extension.

Default: "_frameset".

Specifies the name of the frameset file generated by first pass.

htmlcharset

A valid charset.

Default: "UTF-8".

Specifies which charset to use for the generated HTML files.

htmlextension

File extension (without a leading period).

Default: "html".

Specifies which file extension to use for the generated HTML files.

ignoreresources

true | false

Default: false.

If set to true, do not process resources. That is, treat all resources as if they were external resources.

indexfilename

File basename without any extension.

Default: none.

Specifies that the index is to be generated in a separate HTML file. This option specifies the name of this separate file.

Setting this option generally also requires setting suppressindex to true.

Ignored unless the ebook as specified by the user actually contains an <index/> descendant.

pagenavigation

none | header | footer | both

Default: none.

Specifies whether page navigation headers and/or footers are to be added to the output HTML pages.

The page navigation headers and footers are styled using CSS stylesheet pageNavigation.css found in ebookc_install_dir/xsl/common/resources/.

reservedfilenames

One or more file basenames (without any extension) separated by newline characters.

Default: none.

Do not generate HTML files having any of the specified names.

resourcedirname

File basename without any extension.

Default: "_res".

Specifies the name of the directory where all the resources (e.g. image files, CSS files) referenced in the output HTML pages are stored.

resourcedirnamefor

URL or file path.

Same as resourcedirname except that the name of the resource directory is computed out of the option value. For example, sets the name of the resource directory to "my doc_files" when passed "file:/tmp/my%20doc.epub" or "C:\temp\my doc.epub".

singlepage

true | false

Default: false.

Generate a single HTML page.

suppressindex

true | false

Default: false.

Suppress <index/> from the ebook specification before generating the output HTML pages.

Setting suppressindex to true is generally needed when indexfilename is also specified.

suppresstoc

true | false

Default: false.

Suppress <toc/> from the ebook specification before generating the output HTML pages.

tocframefilename

File basename without any extension.

Default: "_toc_frame".

Specifies the name of the “TOC frame” file generated by first pass.

validate

true | false

Default: true when invoked by the ebookc command-line utility, false otherwise.

Validate the ebook specification against the W3C XML schema found in ebookc_install_dir/schema/ebook.xsd.

-t XSLT_stylesheet_URL_or_file
-xslt XSLT_stylesheet_URL_or_file
Use the specified custom XSLT stylesheet rather than the stock one.
-f html1 | html | webhelp | epub | ps | pdf | rtf | odt | wml | docx | fo | frameset
-format html1 | html | webhelp | epub | ps | pdf | rtf | odt | wml | docx | fo | frameset
Explicitly specifies the output format. By default, the output format is determined using the extension of output_file_or_directory.
Table 9-2. Output formats
Output format Description
html1 Single XHTML5 page.

Automatically detected filename extensions are: "html", "htm", "xhtml", "xhtm" or "xht".

html Multiple XHTML5 pages.
webhelp Web Help
epub EPUB 3
ps PostScript[2]
pdf PDF[2]
rtf RTF (can be opened in Word 2000+)[3]
wml WordprocessingML (can be opened in Word 2003+)[3]
docx Office Open XML (.docx, can be opened in Word 2007+)[3]
odt OpenOffice (.odt, can be opened in OpenOffice/LibreOffice 2+)[3]
fo XSL-FO. Mainly used for debugging and testing purposes.
frameset Multi-page XHTML5 with a frameset and a “TOC frame”. Mainly used for debugging and testing purposes.
-o options_URL_or_file
-option options_URL_or_file
This option lets the user specify a text file containing command-line arguments. This text file has the same format as the ebookc.options file.

Example:

$ ebookc -v -o go.options go.ebook go.epub

If go.options contains:

-p epub-identifier urn:isbn:0451450523
-p cover-image /home/john/artwork/playing_go.png

then this is equivalent to running:

$ ebookc -v -p epub-identifier urn:isbn:0451450523 \
    -p cover-image /home/john/artwork/playing_go.png \
    go.ebook go.epub
-v
-vv
-vvv
Turn verbosity on. More Vs means more verbose.

Command-line options used to configure ebookc

-fop executable_file
Specifies the location of the fop shell script (fop.bat on Windows).

Shorthand for:

-foconverter FOP pdf "executable_file" -q -r -fo "%I" -pdf "%O"
-foconverter FOP ps "executable_file" -q -r -fo "%I" -ps "%O"
-xep executable_file
Specifies the location of the xep shell script (xep.bat on Windows).

Shorthand for:

-foconverter XEP pdf "executable_file" -quiet -valid -fo "%I" -pdf "%O"
-foconverter XEP ps "executable_file" -quiet -valid -fo "%I" -ps "%O"
-ahf executable_file
Specifies the location of AHFCmd.exe (run.sh on platforms other than Windows).

Shorthand for:

-foconverter AHF pdf "executable_file" -x 3 -p @PDF -d "%I\" -o "%O"
-foconverter AHF ps "executable_file" -x 3 -p @PS -d "%I" -o "%O"
-xfc executable_file
Specifies the location of the fo2rtf shell script (fo2rtf.bat on Windows).

Suffice to specify the location of fo2rtf. Using this location, ebookc infers the locations of fo2wml, fo2docx and fo2odt.

Shorthand for:

-foconverter XFC rtf "fo2rtf_executable_file" "%I" "%O"
-foconverter XFC wml "fo2wml_executable_file" "%I" "%O"
-foconverter XFC docx "fo2docx_executable_file" "%I" "%O"
-foconverter XFC odf "fo2odt_executable_file" "%I" "%O"
-foconverter processor_name target_format command
Register specified XSL-FO converter with ebookc, a lower-level alternative to using -xep, -fop, -ahf or -xfc. Example:
-foconverter XFC rtf '/opt/xfc/bin/fo2rtf "%I" "%O"'

Note that this option can be specified several times with different values in the same command-line.

This low-level option may be used for example to specify a configuration file for Apache FOP:

-foconverter FOP pdf \
'/opt/fop/fop -c /home/john/docs/fop.conf -q -r -fo "%I" -pdf "%O"'

Command-line options used to debug ebookc

-dryrun
Use ebookc as a validator, and most notably check cross-references. That is, do not generate any file; just report errors if any.
-errout
Output all messages, including errors and warnings, to stdout.
-ignoreoptionsfile
Do not load the ebookc.options options file. See below The ebookc.options file.
-keepfo
When generating PDF, RTF, DOCX, etc, do not delete the temporary XSL-FO file.
-keepforesources true|yes|on|1 | false|no|off|0
When generating XSL-FO, PDF, RTF, DOCX, etc, do not delete the generated resource directory.

By default, -keepfo implies -keepforesources true.

-version
Print version number and exit.

The ebookc.options file

It is also possible to specify command-line options in the ebookc.options options file. The content of this plain text file, encoded in the native encoding of the platform (e.g. Windows-1252 on a Western Windows PC), is automatically loaded by ebookc each time this command is executed. The content of this file, command-line options separated by whitespace, is prepended to the options specified in the command-line.

Example: If ebookc.options contains:

-v -xep C:\xep\xep.bat

Running:

~/docsrc$ ebookc userguide.ebook out\userguide.pdf

is equivalent to running:

~/docsrc$ ebookc -v -xep C:\xep\xep.bat userguide.ebook out\userguide.pdf

The ebookc.options options file is found in the ebookc user preferences directory. This directory is:

The ebookc.options options file is mainly useful to configure ebookc once for all by specifying values for the -fop, -xep, -xfc, -ahf options.

Example:

-v
-xep E:\opt\xep\xep.bat
-fop E:\opt\fop-2.2\fop\fop.bat
-xfc "E:\opt\xfc_eval_java-5_4_5\bin\fo2rtf.bat"
  • Relative filenames found in this file are relative to the current working directory, and not to the ebookc.options options file. Therefore it is recommended to always specify absolute filenames.
  • No comments (e.g. lines starting with '#') are allowed in ebookc.options. Options must be separated by whitespace.
  • In the above example, FOP is declared after XEP. This implies that it is FOP and not XEP, which will be used by ebookc to generate PDF and PostScript®.
  • An XSL-FO processor tend to consume a lot of memory. If the ebook compilation fails with an out-of-memory error, you need to edit the xep (xep.bat), fop (fop.bat), fo2xxx (fo2xxx.bat) scripts in order to increase the maximum amount of memory that the Java™ runtime may allocate. This is done by using the -Xmx option of the Java™ command-line. Example: "java ... -Xmx512m ...".
  • Starting from Java™ 1.6.0_23, converting XML documents to PDF using RenderX XEP randomly fails with false XSL-FO errors (e.g. attribute "space-before" may not be empty). This problem seems specific to the 64-bit runtime.

    The workarounds for the above bug ("renderx #22766") are:

    • Use a 32-bit Java™ runtime.
    • OR Use a 64-bit Java™ runtime older than 1.6.0_23.
    • OR Specify option -valid in the xep command-line. Note that this workaround is automatically used when you specify which RenderX XEP executable to use by the means of the -xep command-line option.

[1] In other words, when using option -f frameset, ebookc stops after its first pass.

[2] Requires an XSL-FO processor such as Apache FOP, RenderX XEP or Antenna House Formatter to have been installed and registered with XMLmind Ebook Compiler (for example, using option -foconverter).

[3] Requires XMLmind XSL-FO Converter to have been installed and registered with XMLmind Ebook Compiler (using option -xfc).