From f71a40ca0224f4683054fbb9e1cf9fa26561f829 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Fri, 3 Jul 2015 23:26:48 +0000
Subject: tex4ebook (29jul15)

git-svn-id: svn://tug.org/texlive/trunk@37751 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/doc/support/tex4ebook/readme.tex | 326 +++++++++++++++++++++
 1 file changed, 326 insertions(+)
 create mode 100644 Master/texmf-dist/doc/support/tex4ebook/readme.tex

(limited to 'Master/texmf-dist/doc/support/tex4ebook/readme.tex')

diff --git a/Master/texmf-dist/doc/support/tex4ebook/readme.tex b/Master/texmf-dist/doc/support/tex4ebook/readme.tex
new file mode 100644
index 00000000000..cf8a11c0b1c
--- /dev/null
+++ b/Master/texmf-dist/doc/support/tex4ebook/readme.tex
@@ -0,0 +1,326 @@
+\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[-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[-e,--build-file (default nil)]
+Specify \href{https://github.com/michal-h21/make4ht\#build-file}{make4ht
+build file}. Defaulf build file filename is \texttt{filename.mk4}, use
+this option when it has different filename.
+\item[-f,--format (default epub)]
+Output format. epub, epub3 and mobi are supported.
+\item[-l,--lua]
+Runs htlualatex instead of htlatex.
+\item[-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[-r,--resolution]
+Resolution of generated images, for example math. It should meet
+resolution of target devices, which is usually about 167 ppi.
+\item[-s,--shell-escape]
+Enable shell escape in htlatex run. This may be needed if you run
+external commands from your source files.
+\item[t,--tidy]
+Run tidy on output html files.
+\end{description}
+
+\section{Configuration}\label{configuration}
+
+\texttt{tex4ebook} uses \href{http://www.tug.org/tex4ht/}{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
+\href{https://github.com/michal-h21/helpers4ht/wiki/tex4ht-tutorial}{tex4ht
+tutorial} ,
+\href{http://www.tug.org/applications/tex4ht/mn11.html}{tex4ht
+documentation}, and in series of blogposts on CV Radhakrishnan's blog:
+\href{http://www.cvr.cc/?p=323}{Configure part 1},
+\href{http://www.cvr.cc/?p=362}{Configure part 2},
+\href{http://www.cvr.cc/?p=482}{Low level commands}. Available options
+for \texttt{\textbackslash{}Preamble} command are listed in the article
+\href{http://www.cvr.cc/?p=504}{TeX4ht: options}.
+
+Great source of tips for \texttt{tex4ht} configuring is
+\href{http://tex.stackexchange.com/questions/tagged/tex4ht}{tex4ht tag
+on TeX.sx}, there is also a
+\href{http://tex.stackexchange.com/questions/tagged/tex4ebook}{tag for
+tex4ebook}.
+
+Examples of interesting questions are
+\href{including\%20images\%20and\%20fonts\%20in\%20ebooks}{including
+images and fonts in ebooks} or
+\href{http://tex.stackexchange.com/a/195718/2891}{setting image size in
+em units instead of pt}.
+
+\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{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
+\href{http://www.idpf.org/epub/301/spec/epub-publications.html\#sec-item-property-values}{EPUB3
+spec}
+\item[\texttt{\textbackslash{}OpfGuide{[}filename{]}\{title\}\{type\}}]
+Add file to the \texttt{\textless{}guide\textgreater{}} section in the
+\texttt{OPF} file. See
+\href{http://epubsecrets.com/where-do-you-start-an-epub-and-what-is-the-guide-section-of-the-opf-file.php}{Where
+do you start an ePUB and what is the
+\texttt{\textless{}guide\textgreater{}} section of the .OPF file?} 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
+\href{https://github.com/michal-h21/make4ht}{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
+\href{http://tug.org/mailman/listinfo/tex4ht}{tex4ht mailinglist} or on
+\href{http://tex.stackexchange.com/}{TeX-sx}.
+
+\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 conditionaly 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}
+
+Drawback is that not all characters of unicode range are supported with
+\texttt{inputenc}. For some solutions of this limitation, see a thread
+on \href{http://tug.org/pipermail/tex4ht/2013q1/000719.html}{tex4ht
+mailinglist}
+
+\subsection{Validation}\label{validation}
+
+In case of successful compilation, use command line tool
+\texttt{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.
-- 
cgit v1.2.3

