TeX4ebook is bundle of Lua scripts and LaTeX packages for conversion of
LaTeX files to ebook formats, for example epub, mobi and epub3. tex4ht
is used as conversion engine.
Note that while mobi is supported by Amazon Kindle, most widespread ebook
reader, it doesn't support mathml and this means that math must re represented
as images. The same is true for epub. This is not a good thing, especially
for inline math, as you may experience wrong baselines. If your ebook contains
math, the only correct solution is to produce epub3, as it supports mathml.
The issue with epub3 is, that majority of e-ink ebook readers doesn't
support this format, reader applications exists mainly for Android and Apple
devices. For books which contains mainly prose, all formats should be suitable,
but epub3 supports most features from web standards, such as CSS.
As with tex4ht, the emphasis is on conversion of document's logical structure
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 configuration files.
Permission is granted to copy, distribute and/or modify this software under the terms of the LaTeX Project Public License, version 1.3.
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 some
unsupported package like fontspec (see details bellow how to solve this
issue).
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
\coverimage{coverimage.name}- include cover image to the document.
-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^[\url{https://github.com/michal-h21/make4ht#build-file}].
Defaulf build file filename is filename.mk4, use this option if you use
different filename.
-f,--format (default epub)
: Output format. epub, epub3 and mobi are supported.
-l,--lua
: Runs htlualatex instead of htlatex.
-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.
-r,--resolution
: Resolution of generated images, for example math. It should meet resolution of target devices, which is usually about 167 ppi.
-s,--shell-escape
: Enable shell escape in htlatex run. This may be needed if you run external commands from your source files.
-t,--tidy
: process output html files with HTML tidy command^[It needs to be installed separately].
-v,--version
: print version number
tex4ebook uses tex4ht^[\url{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^[\url{https://github.com/michal-h21/helpers4ht/wiki/tex4ht-tutorial}]
, tex4ht documentation^[\url{http://www.tug.org/applications/tex4ht/mn11.html}],
and in series of blogposts on CV Radhakrishnan's blog:
Configure part 1^[\url{http://www.cvr.cc/?p=323}],
Configure part 2^[\url{http://www.cvr.cc/?p=362}],
Low level commands^[\url{http://www.cvr.cc/?p=482}].
Available options for \Preamble command are listed in the article
TeX4ht: options^[\url{http://www.cvr.cc/?p=504}].
Great source of tips for tex4ht configuring is tex4ht tag on TeX.sx^[\url{http://tex.stackexchange.com/questions/tagged/tex4ht}], there is also a tag for tex4ebook^[\url{http://tex.stackexchange.com/questions/tagged/tex4ebook}].
Examples of interesting questions are including images and fonts in ebooks^[\url{http://tex.stackexchange.com/a/213165/2891}] or setting image size in em units instead of pt^[\url{http://tex.stackexchange.com/a/195718/2891}].
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{OpfScheme}{URI}
Type of unique identifier, default type is URI. It is
used only in epub, it is deprecated for epub3
\Configure{DocumentLanguage}{language code}
Each epub 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 xhtml files. Useful in EPUB 3
\OpfRegisterFile[filename]
: register file in the OPF file. Current output file is added by default.
\OpfAddProperty{property type}
: add EPUB3 property for the current file. See EPUB3 spec^[\url{http://www.idpf.org/epub/301/spec/epub-publications.html#sec-item-property-values}]
\OpfGuide[filename]{title}{type}
: Add file to the <guide> section in the OPF file. See Where do you start an ePUB and what is the <guide> section of the .OPF
file?^[\url{http://epubsecrets.com/where-do-you-start-an-epub-and-what-is-the-guide-section-of-the-opf-file.php}]
for some details. Note that <guide> is deprecated in EPUB 3.
tex4ebook uses make4ht^[\url{https://github.com/michal-h21/make4ht}] as a build
system. See make4ht documentation for details on build files.
When compilation of the document breaks with error during LaTeX run, it may
be caused by some problem in tex4ht configuration. Comment out line
\usepackage{tex4ebook} in your source file and run command:
htlatex filename
if same error as in tex4ebook run arises, the problem is in some tex4ht
configuration. Try to identify the source of problem and if you cannot find the
solution, make minimal example showing the error and ask for help either on
tex4ht mailing list^[\url{http://tug.org/mailman/listinfo/tex4ht}] or on
TeX-sx^[\url{http://tex.stackexchange.com/}].
tex4ht currently doesn't support fontspec and open type fonts. At this
moment, workaround for this is to modify your source file and conditionally
include fontspec and any other conflicting packages only when document is not
processed with tex4ht.
Sample:
\documentclass{article}
\makeatletter
\@ifpackageloaded{tex4ht}{%
% Packages for tex4ht unicode support
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[english,czech]{babel}
}{%
% Packages for xelatex
\usepackage{fontspec}
\usepackage{polyglossia}
\setmainfont{Latin Modern Roman}
}
\makeatother
The drawback is that not all characters of the Unicode range are supported with
inputenc. For some solutions of this limitation, see a thread on tex4ht
mailing list^[\url{http://tug.org/pipermail/tex4ht/2013q1/000719.html}]
Other approach is to use alternative4ht package from helpers4ht
bundle. It works only with Lua backend, but it supports full unicode and you
don't have to use conditional package inclusion in your document. See
an example.
In case of successful compilation, use command line tool epubcheck^[you need
to install it separately, see \url{https://github.com/IDPF/epubcheck}] to check
whether your document doesn't contain any errors.
Type
epubcheck filename.epub
- WARNING: filename.epub: item (OEBPS/foo.boo) exists in the zip file, but is not declared in the OPF file
Delete the filename-(epub|epub3|mobi) folder and filename.epub. Then
run tex4ebook again.
-
WARNING(ACC-009): hsmmt10t.epub/OEBPS/hsmmt10tch17.xhtml(235,15): MathML should either have an alt text attribute or annotation-xml child element.
This is accessibility message. Unless you use some macro with annotations for each math instance, you will get lot of these messages. Try to use
epubcheck -eto print only serious errors.