summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/tex4ebook/readme.tex
blob: e5078cfe866f4702534b110711b7b2a7e7989a11 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
\section{Introduction}\label{introduction}

\texttt{TeX4ebook} is bundle of Lua scripts and \texttt{LaTeX} packages
for conversion of LaTeX files to ebook formats, for example
\texttt{epub}, \texttt{mobi} and \texttt{epub3}. \texttt{tex4ht} is used
as conversion engine.

Note that while \texttt{mobi} is supported by Amazon Kindle, most
widespread ebook reader, it doesn't support \texttt{mathml} and this
means that math must re represented as images. The same is true for
\texttt{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 \texttt{epub3}, as it supports
\texttt{mathml}. The issue with \texttt{epub3} is, that majority of
\texttt{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
\texttt{epub3} supports most features from web standards, such as
\texttt{CSS}.

As with \texttt{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 \texttt{CSS} or
fonts in configuration files.

\subsection{License}\label{license}

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

\section{Usage}\label{usage}

Run on the command line:

\begin{verbatim}
tex4ebook [options] filename
\end{verbatim}

You don't have to modify your source files unless you want to use
commands defined by \texttt{tex4ebook} in the document, or when your
document uses some unsupported package like \texttt{fontspec} (see
details bellow how to solve this issue).

If you want to use \texttt{tex4ebook} commands, add this line to your
document preamble:

\begin{verbatim}
\usepackage{tex4ebook}
\end{verbatim}

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

\subsection{Available commands}\label{available-commands}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  \texttt{\textbackslash{}coverimage\{coverimage.name\}} - include cover
  image to the document.
\end{itemize}

\section{Command line options}\label{command-line-options}

\begin{description}
\itemsep1pt\parskip0pt\parsep0pt
\item[\texttt{-c,-{}-config}]
specify custom config file for \texttt{tex4ht}
\end{description}

\textbf{example config file}: File \texttt{sample.cfg}

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

run

\begin{verbatim}
  tex4ebook -c sample filename.tex
\end{verbatim}

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

\begin{description}
\item[\texttt{-e,-{}-build-file (default nil)}]
Specify make4ht build file\footnote{\url{https://github.com/michal-h21/make4ht\#build-file}}.
Defaulf build file filename is \texttt{filename.mk4}, use this option if
you use different filename.
\item[\texttt{-f,-{}-format (default epub)}]
Output format. epub, epub3 and mobi are supported.
\item[\texttt{-l,-{}-lua}]
Runs htlualatex instead of htlatex.
\item[\texttt{-m,-{}-mode (default default)}]
This set \texttt{mode} variable, accessible in the build file. Default
supported values are \texttt{default} and \texttt{draft}. In
\texttt{draft} mode, document is compiled only once, instead of three
times.
\item[\texttt{-r,-{}-resolution}]
Resolution of generated images, for example math. It should meet
resolution of target devices, which is usually about 167 ppi.
\item[\texttt{-s,-{}-shell-escape}]
Enable shell escape in htlatex run. This may be needed if you run
external commands from your source files.
\item[\texttt{-t,-{}-tidy}]
process output html files with \texttt{HTML tidy} command\footnote{It
  needs to be installed separately}.
\item[\texttt{-v,-{}-version}]
print version number
\end{description}

\section{Configuration}\label{configuration}

\texttt{tex4ebook} uses \texttt{tex4ht}\footnote{\url{http://www.tug.org/tex4ht/}}
for conversion from LaTeX to html. \texttt{tex4ht} is highly
configurable using config files. Basic config file structure is

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

Basic info about command configurations can be found in a
work-in-progres \emph{tex4ht tutorial}\footnote{\url{https://github.com/michal-h21/helpers4ht/wiki/tex4ht-tutorial}}
, \emph{tex4ht documentation}\footnote{\url{http://www.tug.org/applications/tex4ht/mn11.html}},
and in series of blogposts on CV Radhakrishnan's blog: \emph{Configure
part 1}\footnote{\url{http://www.cvr.cc/?p=323}}, \emph{Configure part
2}\footnote{\url{http://www.cvr.cc/?p=362}}, \emph{Low level
commands}\footnote{\url{http://www.cvr.cc/?p=482}}. Available options
for \texttt{\textbackslash{}Preamble} command are listed in the article
\emph{TeX4ht: options}\footnote{\url{http://www.cvr.cc/?p=504}}.

Great source of tips for \texttt{tex4ht} configuring is \emph{tex4ht tag
on TeX.sx}\footnote{\url{http://tex.stackexchange.com/questions/tagged/tex4ht}},
there is also a \emph{tag for tex4ebook}\footnote{\url{http://tex.stackexchange.com/questions/tagged/tex4ebook}}.

Examples of interesting questions are \emph{including images and fonts
in ebooks}\footnote{\url{http://tex.stackexchange.com/a/213165/2891}} or
\emph{setting image size in em units instead of pt}\footnote{\url{http://tex.stackexchange.com/a/195718/2891}}.

\subsection{Provided configurations}\label{provided-configurations}

\texttt{tex4ebook} provides some configurations for your usage:

\begin{verbatim}
\Configure{UniqueIdentifier}{identifier}
\end{verbatim}

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

\begin{verbatim}
\Configure{OpfScheme}{URI}
\end{verbatim}

Type of unique identifier, default type is URI. It is used only in epub,
it is deprecated for \texttt{epub3}

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

Configure section types which should be included in the \texttt{NCX}
file. Default value is the whole document hiearchy, from
\texttt{\textbackslash{}part} to \texttt{\textbackslash{}paragraph}.

\begin{verbatim}
\Configure{DocumentLanguage}{language code}
\end{verbatim}

Each epub must declare the document language. It is inferred from
\texttt{babel} main language by default, but you can configure it when
it doesn't work correctly. The \texttt{language code} should be in
\href{https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes}{ISO 639-1}
form.

\begin{verbatim}
\Configure{CoverImage}{before cover image}{after cover image}
\end{verbatim}

By default, cover image is inserted in
\texttt{\textless{}div class="cover-image"\textgreater{}} element, you
may use this configuration option to insert different markup, or even to
place the cover image to standalone page.

\begin{verbatim}
\Configure{CoverMimeType}{mime type of cover image}
\end{verbatim}

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

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

\begin{verbatim}
\CoverMetadata{filename}
\end{verbatim}

in the config file.

\begin{verbatim}
\Configure{OpfMetadata}{item element}
\end{verbatim}

Add item to \texttt{\textless{}metadata\textgreater{}} section in the
\texttt{OPF} file.

\begin{verbatim}
\Configure{OpfManifest}{maifest element}
\end{verbatim}

Add item to \texttt{\textless{}manifest\textgreater{}} section in the
\texttt{OPF} file.

\begin{verbatim}
\Configure{xmlns}{prefix}{uri}
\end{verbatim}

Add xml name space to \texttt{xhtml} files. Useful in \texttt{EPUB 3}

\subsection{Commands available in config
files}\label{commands-available-in-config-files}

\begin{description}
\item[\texttt{\textbackslash{}OpfRegisterFile{[}filename{]}}]
register file in the \texttt{OPF} file. Current output file is added by
default.
\item[\texttt{\textbackslash{}OpfAddProperty\{property type\}}]
add \texttt{EPUB3} property for the current file. See \emph{EPUB3
spec}\footnote{\url{http://www.idpf.org/epub/301/spec/epub-publications.html\#sec-item-property-values}}
\item[\texttt{\textbackslash{}OpfGuide{[}filename{]}\{title\}\{type\}}]
Add file to the \texttt{\textless{}guide\textgreater{}} section in the
\texttt{OPF} file. See \emph{Where do you start an ePUB and what is the
\texttt{\textless{}guide\textgreater{}} section of the .OPF
file?}\footnote{\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 \texttt{\textless{}guide\textgreater{}} is
deprecated in \texttt{EPUB 3}.
\end{description}

\subsection{Build files}\label{build-files}

\texttt{tex4ebook} uses \texttt{make4ht}\footnote{\url{https://github.com/michal-h21/make4ht}}
as a build system. See \texttt{make4ht} documentation for details on
build files.

\section{Troubleshooting}\label{troubleshooting}

When compilation of the document breaks with error during \texttt{LaTeX}
run, it may be caused by some problem in \texttt{tex4ht} configuration.
Comment out line \texttt{\textbackslash{}usepackage\{tex4ebook\}} in
your source file and run command:

\begin{verbatim}
htlatex filename 
\end{verbatim}

if same error as in \texttt{tex4ebook} run arises, the problem is in
some \texttt{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 \emph{tex4ht mailing
list}\footnote{\url{http://tug.org/mailman/listinfo/tex4ht}} or on
\emph{TeX-sx}\footnote{\url{http://tex.stackexchange.com/}}.

\subsection{Fontspec}\label{fontspec}

\texttt{tex4ht} currently doesn't support \texttt{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 \texttt{tex4ht}.

Sample:

\begin{verbatim}
\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
\end{verbatim}

The drawback is that not all characters of the Unicode range are
supported with \texttt{inputenc}. For some solutions of this limitation,
see a thread on \emph{tex4ht mailing list}\footnote{\url{http://tug.org/pipermail/tex4ht/2013q1/000719.html}}

Other approach is to use \texttt{alternative4ht} package from
\href{https://github.com/michal-h21/helpers4ht}{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
\href{http://michal-h21.github.io/samples/helpers4ht/fontspec.html}{example}.

\subsection{Validation}\label{validation}

In case of successful compilation, use command line tool
\texttt{epubcheck}\footnote{you need to install it separately, see
  \url{https://github.com/IDPF/epubcheck}} to check whether your
document doesn't contain any errors.

Type

\begin{verbatim}
epubcheck filename.epub
\end{verbatim}

\subsubsection{Common validation
issues:}\label{common-validation-issues}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  WARNING: filename.epub: item (OEBPS/foo.boo) exists in the zip file,
  but is not declared in the OPF file
\end{itemize}

Delete the \texttt{filename-(epub\textbar{}epub3\textbar{}mobi)} folder
and \texttt{filename.epub}. Then run \texttt{tex4ebook} again.

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  WARNING(ACC-009): hsmmt10t.epub/OEBPS/hsmmt10tch17.xhtml(235,15):
  MathML should either have an alt text attribute or annotation-xml
  child element.
\end{itemize}

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 \texttt{epubcheck -e} to print only serious errors.