From f71a40ca0224f4683054fbb9e1cf9fa26561f829 Mon Sep 17 00:00:00 2001 From: Karl Berry 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