%

Introduction

TeX4ebook is a tool for conversion from \LaTeX\ to ebook formats, such as EPUB, MOBI and EPUB 3. It is based on TeX4ht^[https://tug.org/tex4ht/], which provides instructions for the actual \LaTeX\ to HTML conversion, and on make4ht^[https://ctan.org/pkg/make4ht?lang=en].

The conversion is focused on the logical structure of the converted document and metadata. Basic visual appearance is preserved as well, but you should use custom configurations if you want to make the document more visually appealing. You can include custom CSS or fonts in a configuration file.

TeX4ebook supports the same features as make4ht, in particular build files and extensions. These may be used for post-processing of the generated HTML files, or to configure the image conversion. See the make4ht documentation to see the supported features.

Installation

tex4ebook is included in major \TeX\ distributions such as \TeX\ Live and MiKTeX, so manual installation is usually not required. A working \TeX\ distribution that includes \TeX4ht is required to run tex4ebook, as it depends on \LaTeX\ and various programs and packages provided by \TeX\ distributions.

You only need to install it manually if you want to use the development version. For detailed instructions, see the INSTALL.md file.

License

Permission is granted to copy, distribute and/or modify this software under the terms of the LaTeX Project Public License, version 1.3.

Usage

Run on the command line:

tex4ebook [options] filename

You don't have to modify your source files unless you want to use commands defined by tex4ebook in the document, or when your document uses a package which causes a compilation error.

If you want to use tex4ebook commands, add this line to your document preamble:

\usepackage{tex4ebook}

But it is optional. You shouldn't need to modify your \TeX\ files

Available commands

• \coverimage[<graphicx options>]{coverimage.name} -- include cover image to the document. You can pass the same options as to \includegraphics command in the optional argument.

For example:

\thispagestyle{empty}
\begin{document}
\coverimage[scale=0.8]{coverimage.name} % include scaled cover image
...
\pagestyle{headings}

• \epubpage -- add page break to the document.

Command line options

-a,--loglevel

: Set message log level. Possible values: debug, info, status, warning, error, fatal. Default: status.

-c,--config

: specify custom config file for TeX4ht

example config file: File sample.cfg

  \Preamble{xhtml}
  \CutAt{section}
  \begin{document}
  \EndPreamble

run

  tex4ebook -c sample filename.tex

This config file will create xhtml file for every section. Note that this behaviour is default.

-e,--build-file (default nil)

: Specify make4ht build file^[https://github.com/michal-h21/make4ht#build-file]. Default build file filename is filename.mk4, use this option if you use different filename.

-f,--format (default epub)

: Output format. Possible values are epub, epub3, mobi, azw and azw3.

-j,--jobname

: Specify the output file name, without file extension.

-l,--lua

: Use LuaLaTeX as TeX engine.

-m,--mode (default default)

: This set mode variable, accessible in the build file. Default supported values are default and draft. In draft mode, document is compiled only once, instead of three times.

-s,--shell-escape

: Enable shell escape in the htlatex run. This is necessary for the execution of the external commands from your source files.

-t,--tidy

: clean-up output HTML files using the HTML tidy command^[if it is available on your system].

-x,--xetex

: Use xelatex for document compilation

-v,--version

: Print the version number.

Configuration

TeX4ebook uses TeX4ht^[http://www.tug.org/tex4ht/] for conversion from LaTeX to html. TeX4ht is highly configurable using config files. Basic config file structure is

\Preamble{xhtml, comma separated list of options}
...
\begin{document}
...
\EndPreamble

Basic info about command configurations can be found in a work-in-progres TeX4ht tutorial^[https://github.com/michal-h21/helpers4ht/wiki/tex4ht-tutorial], TeX4ht documentation^[http://www.tug.org/applications/tex4ht/mn11.html], and in series of blogposts on CV Radhakrishnan's blog: Configure part 1^[https://web.archive.org/web/20180908234227/http://www.cvr.cc/?p=323], Configure part 2^[https://web.archive.org/web/20180908201057/http://www.cvr.cc/?p=362], Low level commands^[https://web.archive.org/web/20180909101325/http://cvr.cc/?p=482]. Available options for \Preamble command are listed in the article TeX4ht: options^[https://web.archive.org/web/20180813043722/http://cvr.cc/?p=504]. Comparison of tex4ebook and Pandoc output^[https://github.com/richelbilderbeek/travis_tex_to_epub_example_1]

A great source of tips for TeX4ht configuration is tex4ht tag on TeX.sx^[http://tex.stackexchange.com/questions/tagged/tex4ht]. There is also a tag for tex4ebook^[http://tex.stackexchange.com/questions/tagged/tex4ebook].

Examples of interesting questions are including images and fonts in ebooks^[http://tex.stackexchange.com/a/213165/2891] or setting image size in em units instead of pt^[http://tex.stackexchange.com/a/195718/2891].

Provided configurations

tex4ebook provides some configurations for your usage:

\Configure{UniqueIdentifier}{identifier}

Every EPUB file should have unique identifier, like ISBN, DOI, URI etc. Default identifier is URI, with value http://example.com/\jobname.

\Configure{@author}{\let\footnote\@gobble}

Local definitions of commands used in the \author command. As contents of \author are used in XML files, it is necessary to strip away any information which don't belongs here, such as \footnote.

\Configure{OpfScheme}{URI}

Type of unique identifier, default type is URI. It is used only in the EPUB format, it is deprecated for EPUB 3.

\Configure{resettoclevels}{list of section types in descending order}

Configure section types which should be included in the NCX file. Default value is the whole document hierarchy, from \part to \paragraph.

\Configure{DocumentLanguage}{language code}

Each EPUB file must declare the document language. It is inferred from babel main language by default, but you can configure it when it doesn't work correctly. The language code should be in ISO 639-1 form.

\Configure{CoverImage}{before cover image}{after cover image}

By default, cover image is inserted in <div class="cover-image"> element, you may use this configuration option to insert different markup, or even to place the cover image to standalone page.

\Configure{CoverMimeType}{mime type of cover image}

Default value is image/png, change this value if you use other image type than png.

If you don't want to include the cover image in the document, use command

\CoverMetadata{filename}

in the config file.

\Configure{OpfMetadata}{item element}

Add item to <metadata> section in the OPF file.

\Configure{OpfManifest}{maifest element}

Add item to <manifest> section in the OPF file.

\Configure{xmlns}{prefix}{uri}

Add XML name space to the generated XHTML files. Useful in EPUB 3.

Example config file

\Preamble{xhtml}
\begin{document}
\Configure{DocumentLanguage}{de}
% Use following lines if your document has ISBN:
% \Configure{OpfScheme}{ISBN}
% \Configure{UniqueIdentifier}{3-0000-1111-X}
% Another possibility is URI that points for example to the ebook homepage:
\Configure{OpfScheme}{URI}
\Configure{UniqueIdentifier}
{https://de.wikipedia.org/wiki/Der_achte_Schöpfungstag}
\Configure{CoverMimeType}{image/jpeg}
% If you don't use \coverimage in the document text, 
% add cover image using this command:
\CoverMetadata{coverimage.jpg}
% You can also add more authors to your ebook metadata:
\Configure{OpfMetadata}
{\HCode{<dc:publisher>Deutscher Bücherbund</dc:publisher>}}
\Configure{OpfMetadata}
{\HCode{<dc:contributor>Image Artist</dc:contributor>}}
\Configure{OpfMetadata}
{\HCode{<dc:contributor>Trans Lator</dc:contributor>}}
\Configure{OpfMetadata}
{\HCode{<dc:date opf:event='original-publication'>1888</dc:date>}}
\EndPreamble

Remarks:

• Leading percent signs in the .cfg file introduce comments
• If the unique identifier is a URI which contains diacritical characters, the
  equivalent HTML code needs to be inserted. UTF8 is not recognized at that place.
• UTF8 characters may be used in the OpfMetadata sections.

\TeX4ht options

\TeX4ht supports lot of options, that change produced HTML code without need to use configurations. Their list is available in the \TeX4ht documentation. You can pass options to tex4ebook in the argument that follows filename:

tex4ebook filename.tex "option1,option2"

Alternatively, they can be put in the \Preamble command in the config file:

\Preamble{xhtml,option1,option2}

Options provided by tex4ebook

no-cut

: By default tex4ebook splits document to separate HTML pages on \chapter command when it is available. Othervise, it splits on \section. This can be changed using the \CutAt command or numeric options, but you need to use the no-cut option to prevent fatal error.

Commands availab