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.3. Conditional processing.

"load.page_loader_name." parameters

A param_name starting with "load.page_loader_name." specifies an option which is passed to the alternate page loader called page_loader_name. For example, -p load.markdown.autolink true turns on the autolink extension in the Markdown loader. See Supported Markdown extensions.

"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
copiablelinks	List of values separated by whitespace. Allowed values are: 'part', 'chapter', 'section', 'figure', 'table', 'heading', 'all' (equivalent to 'chapter section figure table'; 'part' and 'heading' not included in this list). Default value: '' (do not add copiable links).	Adds a copiable link to the heading or caption child elements of specified “formal elements”. If the “formal element” is numbered (e.g. has a "Chapter 1." automatically generated label), then the automatically generated label is converted to a link. This link points to the formal element (e.g. a link to the section having a chapter role). Otherwise (e.g. a table which is not numbered), a link containing the section symbol, "§", is added to the heading or caption. This link points to the formal element (e.g. a link to the table). This automatically generated link to a formal element is intended to be copied using the "Copy Link" entry found in the contextual menu of all web browsers in order to be shared with others. For example, send this link by email. For this facility to work, the formal element must have an id attribute, whether specified by the author or automatically generated by ebookc. It does not make sense to use this parameter when generating EPUB or any XSL-FO based output format (PDF, RTF, etc). Use it only when generating HTML or Web Help.
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"'

No matter the order of command-line options, option -foconverter has priority over options -fop, -xep, -ahf, -xfc, which is turn have priority over bundled XSL-FO converters (such as the Apache FOP contained in ebookc-N_N_N-plus-fop.zip distributions).

-fopconf configuration_file

Specifies the location of an Apache FOP configuration file. A relative file path is relative to the current working directory. Ignored unless option -fop is also specified.

-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"'

-ahfconf configuration_file

Specifies the location of an Antenna House Formatter configuration file. A relative file path is relative to the current working directory. Ignored unless option -ahf is also specified.

-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"'

XMLmind XSL-FO Converter Evaluation Edition (download page) generates output containing random duplicate letters. This makes this edition useless for any purpose other than evaluating XMLmind XSL-FO Converter. Of course, this does not happen with XMLmind XSL-FO Converter Professional Edition!

-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"'

No matter the order of command-line options, option -foconverter has priority over options -fop, -xep, -ahf, -xfc, which is turn have priority over bundled XSL-FO converters (such as the Apache FOP contained in ebookc-N_N_N-plus-fop.zip distributions).

§ 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:

• $HOME/.ebookc/ on Linux.
• $HOME/Library/Application Support/XMLmind/ebookc/ on the Mac.
• %APPDATA%\XMLmind\ebookc\ on Windows. Example: C:\Users\john\AppData\Roaming\XMLmind\ebookc\.

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\fop\fop.bat
-xfc "E:\opt\xfc\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.