The tex4ebook package

Michal Hoftich

∗

Version v0.4

2024-02-23

Contents

1 Introduction 2

1.1 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 Usage 2

2.1 Available commands . . . . . . . . . . . . . . . . . . . . . . . . 2

3 Command line options 3

4 Conguration 4

4.1 Provided congurations . . . . . . . . . . . . . . . . . . . . . . . 4

4.1.1 Example cong le . . . . . . . . . . . . . . . . . . . . . 6

4.2 T

X4ht options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4.2.1 Options provided by tex4ebook . . . . . . . . . . . . . . 7

4.3 Commands available in the cong le . . . . . . . . . . . . . . 7

4.4 Build les . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.5 .tex4ebook conguration le . . . . . . . . . . . . . . . . . . . 8

4.5.1 Location . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

5 Troubleshooting 8

5.1 Kindle formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

5.2 Fixed layout EPUB . . . . . . . . . . . . . . . . . . . . . . . . . 8

5.3 Math issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

5.4 Compilation errors . . . . . . . . . . . . . . . . . . . . . . . . . 9

5.5 Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

5.5.1 Common validation issues: . . . . . . . . . . . . . . . . . 9

6 Changes 10

∗

[email protected]

1 Introduction

TeX4ebook

is a tool for conversion from L

X to ebook formats, such as EPUB,

MOBI and EPUB 3. It is based on

TeX4ht

, which provides instructions for

the actual L

X to HTML conversion, and on make4ht

The conversion is focused on the logical structure of the converted docu-

ment and metadata. Basic visual appearance is preserved as well, but you

should use custom congurations if you want to make the document more

visually appealing. You can include custom

CSS

or fonts in a conguration

le.

TeX4ebook

supports the same features as

make4ht

, in particular build

les and extensions. These may be used for post-processing of the gener-

ated HTML les, or to congure the image conversion. See the

make4ht

documentation to see the supported features.

1.1 License

Permission is granted to copy, distribute and/or modify this software under

the terms of the LaTeX Project Public License, version 1.3.

2 Usage

Run on the command line:

tex4ebook [options] filename

You don’t have to modify your source les unless you want to use com-

mands dened 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 T

X les

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

https://tug.org/tex4ht/

https://ctan.org/pkg/make4ht?lang=en

\thispagestyle{empty}

\begin{document}

\coverimage[scale=0.8]{coverimage.name} % include scaled cover image

...

\pagestyle{headings}

• \epubpage – add page break to the document.

3 Command line options

-a,--loglevel

Set message log level. Possible values: debug, info, status,

warning, error, fatal. Default: status.

-c,--config specify custom cong le for TeX4ht

example cong le: File sample.cfg

\Preamble{xhtml}

\CutAt{section}

\begin{document}

\EndPreamble

run

tex4ebook -c sample filename.tex

This cong le will create

xhtml

le for every section. Note that this

behaviour is default.

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

Specify make4ht build le

. Default build

le lename is

filename.mk4

, use this option if you use dierent le-

name.

-f,--format (default epub)

Output format. Possible values are

epub

epub3

mobi, azw and azw3.

-j,--jobname Specify the output le name, without le extension.

-l,--lua Use LuaLaTeX as TeX engine.

-m,--mode (default default)

This set

mode

variable, accessible in the build

le. 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 nec-

essary for the execution of the external commands from your source

les.

https://github.com/michal-h21/make4ht#build-file

-t,--tidy clean-up output HTML les using the HTML tidy command

-x,--xetex Use xelatex for document compilation

-v,--version Print the version number.

4 Conguration

TeX4ebook

uses

TeX4ht

for conversion from LaTeX to html.

TeX4ht

is highly

congurable using cong les. Basic cong le structure is

\Preamble{xhtml, comma separated list of options}

...

\begin{document}

...

\EndPreamble

Basic info about command congurations can be found in a work-in-

progres TeX4ht tutorial

, TeX4ht documentation

, and in series of blogposts

on CV Radhakrishnan’s blog: Congure part 1

, Congure part 2

, Low level

commands

. Available options for

\Preamble

command are listed in the

article TeX4ht: options

. Comparison of tex4ebook and Pandoc output

A great source of tips for

TeX4ht

conguration is tex4ht tag on TeX.sx

There is also a tag for tex4ebook

Examples of interesting questions are including images and fonts in

ebooks

or setting image size in em units instead of pt

4.1 Provided congurations

tex4ebook provides some congurations for your usage:

\Configure{UniqueIdentifier}{identifier}

Every EPUB le should have unique identier, like ISBN, DOI, URI etc.

Default identier is URI, with value http://example.com/\jobname.

if it is available on your system

http://www.tug.org/tex4ht/

https://github.com/michal-h21/helpers4ht/wiki/tex4ht-tutorial

http://www.tug.org/applications/tex4ht/mn11.html

https://web.archive.org/web/20180908234227/http://www.cvr.cc/?p=323

https://web.archive.org/web/20180908201057/http://www.cvr.cc/?p=362

https://web.archive.org/web/20180909101325/http://cvr.cc/?p=482

https://web.archive.org/web/20180813043722/http://cvr.cc/?p=504

https://github.com/richelbilderbeek/travis_tex_to_epub_example_1

http://tex.stackexchange.com/questions/tagged/tex4ht

http://tex.stackexchange.com/questions/tagged/tex4ebook

http://tex.stackexchange.com/a/213165/2891

http://tex.stackexchange.com/a/195718/2891

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

Local denitions of commands used in the

\author

command. As contents

\author

are used in XML les, it is necessary to strip away any information

which don’t belongs here, such as \footnote.

\Configure{OpfScheme}{URI}

Type of unique identier, 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}

Congure section types which should be included in the

NCX

le. Default

value is the whole document hierarchy, from \part to \paragraph.

\Configure{DocumentLanguage}{language code}

Each EPUB le must declare the document language. It is inferred from

babel

main language by default, but you can congure 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

ele-

ment, you may use this conguration option to insert dierent 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 cong le.

\Configure{OpfMetadata}{item element}

Add item to <metadata> section in the OPF le.

\Configure{OpfManifest}{maifest element}

Add item to <manifest> section in the OPF le.

\Configure{xmlns}{prefix}{uri}

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

4.1.1 Example cong le

\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 le introduce comments

•

If the unique identier 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.

4.2 T

X4ht options

X4ht supports lot of options, that change produced HTML code without

need to use congurations. Their list is available in the T

X4ht documen-

tation. You can pass options to

tex4ebook

in the argument that follows

lename:

tex4ebook filename.tex "option1,option2"

Alternatively, they can be put in the

\Preamble

command in the cong

le:

\Preamble{xhtml,option1,option2}

4.2.1 Options provided by tex4ebook

no-cut

By default

tex4ebook

splits document to separate HTML pages

\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.

4.3 Commands available in the cong le

\OpfRegisterFile[filename]

OPF

le. Current output

le is added by default.

\OpfAddProperty{property type}

add

EPUB3

property for the current le.

See EPUB3 spec

\OpfGuide[filename]{title}{type}

Add le to the

<guide>

section in the

OPF

le. See Where do you start an ePUB and what is the

<guide>

section

of the

.OPF

le?

for some details. Note that

<guide>

is deprecated in

EPUB 3.

4.4 Build les

tex4ebook

uses

make4ht

as a build system. It provides support for build

les written in Lua. These build les can be used to call additional commands,

like BibT

X or Makeindex, post-process generated HTML les, change the

way how images are created, or to modify parameters of the conversion.

Sample build le can look like this:

if mode=="draft" then

Make:htlatex {}

else

Make:htlatex {}

end

Make:image("png$",

"dvipng -bg Transparent -T tight -o ${output} -D 170 -pp ${page} ${source}")

http://www.idpf.org/epub/301/spec/epub-publications.html#

sec-item-property-values

http://epubsecrets.com/where-do-you-start-an-epub-and-what-is-the-guide-section-of-the-opf-file.

php

https://github.com/michal-h21/make4ht

The

mode

variable holds value of the

--mode

argument to

tex4ebook

. The

draft mode is used for faster compilation, it calls LaTeX only once.

The

Make:image

function can congure handling of images created by

extraction from the DVI le. It can be complex math, TikZ or PSTricks

pictures, and so on. The

${<name>}

placeholders are lled by

tex4ebook

with

parameters like current page number of the image DVI le, or output image

name.

You can compile your document with a build le using the -e option:

tex4ebook -m draft -e build.lua filename.tex

See make4ht documentation for more details on conguration les.

4.5 .tex4ebook conguration le

tex4ebook

supports a default build le, which is loaded automatically without

need to use the -e option.

4.5.1 Location

The conguration le can be saved either in

$HOME/.config/tex4ebook/config.lua

or in .tex4ebook in the current directory or it’s parents (up to $HOME).

See the make4ht documentation for an example and more information.

5 Troubleshooting

5.1 Kindle formats

tex4ebook

uses

kindlegen

command for the conversion to Kindle formats

(

mobi

azw

and

azw3

). Unfortunatelly, Amazon discontinued this command,

so we use also ebook-convert provided by Calibre if kindlegen fails.

5.2 Fixed layout EPUB

The basic support for the Fixed layout EPUB 3 can be enabled using the

following congurations:

\Configure{OpfMetadata}

{\HCode{<meta property="rendition:layout">pre-paginated</meta>}}

\Configure{OpfMetadata}

{\HCode{<meta property="rendition:orientation">landscape</meta>}}

\Configure{OpfMetadata}

{\HCode{<meta property="rendition:spread">none</meta>}}

\Configure{@HEAD}

{\HCode{<meta name="viewport" content="width=1920, height=1080"/>\Hnewline}}

Modify the dimensions in the

element according

to your needs.

5.3 Math issues

Note that while

mobi

is supported by Amazon Kindle, most widespread ebook

reader, it doesn’t support

MathML

. This means that math must be represented

as images. The same issue is true for the EPUB format as well. This is

problematic especially for the inline math, as you may experience wrong

vertical alignment of the math content and surrounding text. If your ebook

contains math, a better solution is to produce the

epub3

format, as it supports

MathML

. The issue with EPUB 3 is that majority of

e-ink

ebook readers don’t

support it. Reader applications exists mainly for Android and Apple devices.

For books which contains mainly prose, all formats should be suitable, but

EPUB 3 supports most features from web standards, such as CSS.

5.4 Compilation errors

When compilation of the document breaks with error during

LaTeX

run, it

may be caused by some problem in

TeX4ht

conguration. Comment out line

\usepackage{tex4ebook} in your source le and run command:

htlatex filename

if same error as in

tex4ebook

run arises, the problem is in some

TeX4ht

conguration. Try to identify the source of problem and if you cannot nd the

solution, make minimal example showing the error and ask for help either

on TeX4ht mailing list

or on TeX.sx

5.5 Validation

In case of successful compilation, use command line tool

epubcheck

to check

whether your document doesn’t contain any errors.

Type

epubcheck filename.epub

5.5.1 Common validation issues:

•

WARNING: lename.epub: item (OEBPS/foo.boo) exists in the zip le,

but is not declared in the OPF le

Delete the

filename-(epub|epub3|mobi|azw|azw3)

folder and

filename.epub

Then run tex4ebook again.

http://tug.org/mailman/listinfo/tex4ht

http://tex.stackexchange.com/

you need to install it separately, see https://github.com/IDPF/epubcheck

•

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 annota-

tions for each math instance, you will get lot of these messages. Try to

use epubcheck -e to print only serious errors.

6 Changes

• 2024/02/23

– version 0.4 released.

• 2023/10/30

– added the \epubpage command

• 2023/10/17

– added the --build-dir command line option.

• 2023/10/15

– don’t set PNG as image format explicitly.

• 2023/06/02

– prevent fatal errors in the zip command executable detection.

• 2023/05/29

– save author and date globally.

• 2023/05/23

– removed spurious numbers from TOC in Epub 3.

• 2023/03/17

– released version 0.3j.

– xed bug in generating of TOC in the NCX le.

• 2023/03/02

– released verision 0.3i.

– check if le with TOC exists before processing.

• 2023/01/12

– added all mimetypes supported in Epub.

• 2023/01/09

–

xed handling of metadata for lenames with accented characters.

• 2022/12/15

– use lower case le extensions for mimetype matching.

• 2022/12/01

– set destinations for \label used inside of footnotes.

– xed handling of multiple tables of contents in Epub 3.

• 2022/11/20

– added support for the fn-in option in the Epub 3 output.

• 2022/03/29

– xed support for T

X lenames that contain dot.

– removed spurious comma that was introduced earlier.

• 2022/03/28

– documented the no-cut option.

• 2022/02/23

– extended the documentation about build les.

– deprecated the --resolution CLI argument.

• 2022/02/22

– print \subsubsection in the Epub TOC.

• 2022/02/18

– released version 0.3h.

• 2022/01/13

–

xed issue where child TOC elements were inserted into

<a>

ele-

ment.

• 2021/12/07

– print space after section number in Epub 3 TOC.

– keep original elements in Epub 3 TOC.

• 2021/12/04

– xed support for appendix chapters in Epub 3.

• 2021/11/08

– released version 0.3g

– bug x: removed spurious 0 character from the NCX le.

• 2021/11/05

– released version 0.3f

–

xed spurious numbers in NCX TOC caused by wrong use of

\cs_if_exist_use:cTF command.

• 2021/10/08

– x for \author support in amsart class.

• 2021/09/30

– released version 0.3e

– better detection if kindlegen was found.

• 2021/09/23

–

use

ebook-convert

for convertsion to Kindle formats if

kindlegen

fails.

• 2021/08/22

– xed cross-referencing issue related to unnumbered equations.

• 2021/07/26

– released version 0.3d

• 2021/05/29

–

renamed

DeclareLanguage

\DeclareLanguageEbook

. Fixes is-

sue 78.

• 2021/05/15

– use assert in checking of existence of the zip command.

–

replace colons in

OPF id

attributes and add trailing

if the

starts with number. It should x some validation issues.

• 2021/05/02

– added more examples of conguration to the documentation.

• 2020/11/09

– set exit status

• 2020/11/09

– don’t redene PicDisplay conguration.

• 2020/11/06

–

bug x: remove custom elements from the NCX le in the Epub 3

format.

– released version 0.3c

• 2020/09/07

– released version 0.3b

• 2020/08/26

–

xed hiearchical structure in NCX TOC for chapters in backmatter

and appendix

– load common_domfilters extension by default.

• 2020/07/09

– addded AZW and AZW3 format support.

• 2020/06/21

– save \title element

– save contents of \author in macro directly

• 2020/06/15

–

remove child elements from elements that don’t allow them in the

OPF and NCX le.

• 2020/03/14

– explicitly list supported section types in the NCX table

• 2019/11/01

– released version 0.3a

– added tex4ebook- prex to the output formats.

– removed unused les.

• 2019/11/01

– released version 0.3

• 2019/10/20

– xed the TOC cleanup in the ePub 3 mode.

–

added support for the

page-spread-left

and

page-spreat-right

properties.

• 2019/10/20

– addapted to use the make4ht logging mechanism.

• 2019/10/06

– xed bug with void elements parsing in the OPF le.

–

undo

\XeTeXcharclass

for the

character when the OPF le is

generated.

• 2019/09/16

–

make the default build sequence before loading of the extensions.

Some extensions need to modify the build sequence.

• 2019/08/28

– added support for reading input from STDIN.

• 2019/08/27

– added support for the --jobname command line option.

• 2019/08/25

–

use the

mkparams.get_args

function to retrieve the command line

options

• 2019/07/24

–

added support for the

\author

command with an optional argu-

ment

• 2019/05/09

–

added support for the

\title

command with an optional argument

• 2019/04/04

– register appendix chapters and section in the OPF le list

– xed handling of appendices in the NCX table of contents

• 2019/03/21

– released version 0.2c

• 2019/03/07

–

use

Luatexbase

package in the documentation because of

Microtype

error

– remove <guide> element even in ePub 2

–

added

encoding

attribute to XML declaration in the NCX and OPF

les

–

clean the temporary directory (

filename-format

) before le pack-

ing

• 2019/01/21

– added \Configure{@author}

• 2019/01/10

– released version 0.2b

• 28/11/2018

– added support for appendix sections to the NCX le

• 27/11/2018

–

use the

uni-html4

option by default. It will convert some math

characters as Unicode chars

• 13/11/2018

– added –xetex option to the README

• 30/10/2018

–

use the original section numbering in TOC in the Epub 3 output.

The numbering of the <ol> list is disabled by CSS.

• 18/10/2018

– xed the executable installation

• 03/09/2018

– updated the --help message

• 30/08/2018

–

removed spurious

\NoFonts

command in the footnote conguration,

it caused formating issues in the document following a footnote

• 22/06/2018

– added support for the output directory selection

• 09/05/2018

– added support for Polyglossia language codes

– released version 0.2a

• 03/05/2018

– xed output format handling

• 16/04/2018

– don’t run Git if the Makele is executed outside of Git repo

• 09/04/2018

– released version 0.2

• 06/04/2018

– documented the conguration le

• 02/03/2018

– added support for .tex4ebook conguration le

• 28/02/2018

– added media overlays handling

• 19/10/2017

– added support for XeTeX

• 06/10/2017

– added support for Make4ht extensions

• 27/04/2017 Version 0.1e

– pack the accumulated changes for distribution

– set version number from git tag

• 17/01/2017

– process duplicate images only once

– check the OPF table for duplicated id attributes

• 11/01/2017

– pass settings table to the build le.

• 19/12/2016

–

new conguration:

\Configure{resettoclevels}{list of sectioning

levels to be included in the NCX}

• 31/10/2016

– added tidyconf.conf to the Makele

• 22/10/2016

– added support for new Make4ht command Make:add_file

• 22/08/2016

– xed incorrect <dc:creator> generated by \author

–

clean ids in the OPF le if they contain invalid characters at the

beginning

• 31/07/2016

–

use monospace font for command line options in order to prevent

double hyphens to become dashes by ligaturing

• 22/07/2016

– removed debugging message when --lua option is used

• 07/04/2016

– Cut \part commands to standalone pages

• 05/04/2016

–

bug x: pages which contained math were arranged before other

pages

• 31/03/2016 Version 0.1d

– bug x: Unicode wasn’t used by default

– bug x: Formats weren’t preserved

• 06/12/2015 Version 0.1c

– added --help and --version command line options

• 25/11/2015

– added missing language codes

–

added

\Configure{DocumentLanguage}

for the cases when docu-

ment language inferencing doesn’t work

• 17/11/2015

– use mkparams for cli arguments handling.

–

xed inconsistencies between recent changes in make4ht and

tex4ebook

• 24/09/2015 Version 0.1b

– info about new workaround for fontspec package

• 25/08/2015

–

fatal error happened with epub3 when the document didn’t contain

the TOC

• 23/08/2015

– simple cleaning of the ncx le if tidy command isn’t available

• 05/07/2015 Version 0.1a

– tex4ebook script was missing in the distribution zip le

– all links moved to footnotes in the documentation

• 29/06/2015 Version 0.1

– xes in documentation

• 22/06/2015

– changes moved from README.md to CHANGELOG.md

• 18/06/2015

–

replaced

--mathml

option with

--mode

. For

mathml

support, use

mathml

option for tex4ht.sty.

– lot of stu was xed in epub3 support.

– new command \OpfAddProperty

• 14/01/2015

- thanks Volker Gottwald for guide on [installing and using

tex4ebook](https://d800fotos.wordpress.com/2015/01/19/create-

e-books-from-latex-tex-files-ebook-aus-latex-tex-dateien-erstellen/)

on Windows

• 23/11/2014

- added new command `\OpfGuide`, for adding items to `<guide>`

section in the `opf` file. This is useful for `epub` and `mobi` formats.

Usage:

\OpfGuide[filename]{title}{reference type}

`filename` is optional, current file name is used when empty. See

[epub

secrets](http://epubsecrets.com/where-do-you-start-an-epub-

and-what-is-the-guide-section-of-the-opf-file.php)

article

• 20/10/2014

- fixed issues with starred sections

- files created with starred sectioning commands (`\chapter*`,

`\section*`) should be included in correct reading order now

• 16/09/2014

- new features added

- new configuration file for `--tidy` option, mathml and html5 elements

are supported. This means that many validation errors in `mathml`

output can be fixed with `--tidy` option

- added configuration for all languages supported by `babel`

- `woff` and `ttf` fonts are supported

- added inline footlines in `epub3` format

- added `no-cut` command line option for breaking sections and chapters

into standalone pages

- Please support [iniciative for improving mathml

support](http://www.ulule.com/mathematics-ebooks/) in Gecko and Webkit

engines. This will hopefully improve also Epub3 readers.

• 10/08/2013

- [`make4ht`](https://github.com/michal-h21/make4ht) is now standalone

application which `tex4ebook` depends on. You must [install

it](https://github.com/michal-h21/make4ht#instalation) in order to use

current tex4ebook version.