summaryrefslogtreecommitdiff
path: root/support/tex4ebook/readme.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/tex4ebook/readme.tex
Initial commit
Diffstat (limited to 'support/tex4ebook/readme.tex')
-rw-r--r--support/tex4ebook/readme.tex350
1 files changed, 350 insertions, 0 deletions
diff --git a/support/tex4ebook/readme.tex b/support/tex4ebook/readme.tex
new file mode 100644
index 0000000000..2a6110e03f
--- /dev/null
+++ b/support/tex4ebook/readme.tex
@@ -0,0 +1,350 @@
+\hypertarget{introduction}{%
+\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.
+
+\hypertarget{license}{%
+\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.
+
+\hypertarget{usage}{%
+\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 a package which causes a compilation error.
+
+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
+
+\hypertarget{available-commands}{%
+\subsection{Available commands}\label{available-commands}}
+
+\begin{itemize}
+\tightlist
+\item
+ \texttt{\textbackslash{}coverimage\{coverimage.name\}} - include cover
+ image to the document.
+\end{itemize}
+
+\hypertarget{command-line-options}{%
+\section{Command line options}\label{command-line-options}}
+
+\begin{description}
+\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 formats are supported.
+\item[\texttt{-l,-\/-lua}]
+Use LuaLaTeX as TeX engine.
+\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{-x,-\/-xetex}]
+Use xelatex for document compilation
+\item[\texttt{-v,-\/-version}]
+Print the version number.
+\end{description}
+
+\hypertarget{configuration}{%
+\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}}.
+\emph{Comparison of tex4ebook and Pandoc output}\footnote{\url{https://github.com/richelbilderbeek/travis_tex_to_epub_example_1}}
+
+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}}.
+
+\hypertarget{provided-configurations}{%
+\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{@author}{\let\footnote\@gobble}
+\end{verbatim}
+
+Local definitions of commands used in the
+\texttt{\textbackslash{}author} command. As contents of
+\texttt{\textbackslash{}author} are used in XML files, it is necessary
+to strip away any information which don't belongs here, such as
+\texttt{\textbackslash{}footnote}.
+
+\begin{verbatim}
+\Configure{OpfScheme}{URI}
+\end{verbatim}
+
+Type of unique identifier, default type is URI. It is used only in
+\texttt{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 hierarchy, from
+\texttt{\textbackslash{}part} to \texttt{\textbackslash{}paragraph}.
+
+\begin{verbatim}
+\Configure{DocumentLanguage}{language code}
+\end{verbatim}
+
+Each ePub file 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}
+
+\hypertarget{commands-available-in-config-files}{%
+\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 \texttt{.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}
+
+\hypertarget{build-files}{%
+\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.
+
+\hypertarget{tex4ebook-configuration-file}{%
+\subsection{\texorpdfstring{\texttt{.tex4ebook} configuration
+file}{.tex4ebook configuration file}}\label{tex4ebook-configuration-file}}
+
+It is possible to globally modify the build settings using the
+configuration file. New compilation commands can be added, extensions
+can be loaded or disabled and settings can be set.
+
+\hypertarget{location}{%
+\subsubsection{Location}\label{location}}
+
+The configuration file can be saved either in
+\texttt{\$HOME/.config/tex4ebook/config.lua} or in \texttt{.tex4ebook}
+in the current directory or it's parents (up to \texttt{\$HOME}).
+
+See the \texttt{make4ht} documentation for an example and more
+information.
+
+\hypertarget{troubleshooting}{%
+\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/}}.
+
+\hypertarget{validation}{%
+\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}
+
+\hypertarget{common-validation-issues}{%
+\subsubsection{Common validation
+issues:}\label{common-validation-issues}}
+
+\begin{itemize}
+\tightlist
+\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}
+\item
+ 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 \texttt{epubcheck\ -e} to print only serious
+ errors.
+\end{itemize}