diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/tex4ebook/readme.tex |
Initial commit
Diffstat (limited to 'support/tex4ebook/readme.tex')
-rw-r--r-- | support/tex4ebook/readme.tex | 350 |
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} |