diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/tex4ebook/readme.tex')
-rw-r--r-- | Master/texmf-dist/doc/support/tex4ebook/readme.tex | 103 |
1 files changed, 67 insertions, 36 deletions
diff --git a/Master/texmf-dist/doc/support/tex4ebook/readme.tex b/Master/texmf-dist/doc/support/tex4ebook/readme.tex index e5078cfe866..e8ef08d4df8 100644 --- a/Master/texmf-dist/doc/support/tex4ebook/readme.tex +++ b/Master/texmf-dist/doc/support/tex4ebook/readme.tex @@ -1,4 +1,5 @@ -\section{Introduction}\label{introduction} +\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 @@ -24,12 +25,14 @@ 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} +\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. -\section{Usage}\label{usage} +\hypertarget{usage}{% +\section{Usage}\label{usage}} Run on the command line: @@ -51,20 +54,21 @@ document preamble: but it is optional. You shouldn't need to modify your \TeX~files -\subsection{Available commands}\label{available-commands} +\hypertarget{available-commands}{% +\subsection{Available commands}\label{available-commands}} \begin{itemize} -\itemsep1pt\parskip0pt\parsep0pt +\tightlist \item \texttt{\textbackslash{}coverimage\{coverimage.name\}} - include cover image to the document. \end{itemize} -\section{Command line options}\label{command-line-options} +\hypertarget{command-line-options}{% +\section{Command line options}\label{command-line-options}} \begin{description} -\itemsep1pt\parskip0pt\parsep0pt -\item[\texttt{-c,-{}-config}] +\item[\texttt{-c,-\/-config}] specify custom config file for \texttt{tex4ht} \end{description} @@ -87,33 +91,34 @@ 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)}] +\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)}] +\item[\texttt{-f,-\/-format\ (default\ epub)}] Output format. epub, epub3 and mobi are supported. -\item[\texttt{-l,-{}-lua}] +\item[\texttt{-l,-\/-lua}] Runs htlualatex instead of htlatex. -\item[\texttt{-m,-{}-mode (default default)}] +\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}] +\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}] +\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 +\item[\texttt{-t,-\/-tidy}] +process output html files with \texttt{HTML\ tidy} command\footnote{It needs to be installed separately}. -\item[\texttt{-v,-{}-version}] +\item[\texttt{-v,-\/-version}] print version number \end{description} -\section{Configuration}\label{configuration} +\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 @@ -136,6 +141,7 @@ part 1}\footnote{\url{http://www.cvr.cc/?p=323}}, \emph{Configure part 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}}, @@ -145,7 +151,8 @@ 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} +\hypertarget{provided-configurations}{% +\subsection{Provided configurations}\label{provided-configurations}} \texttt{tex4ebook} provides some configurations for your usage: @@ -178,7 +185,7 @@ file. Default value is the whole document hiearchy, from 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 +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. @@ -187,7 +194,7 @@ form. \end{verbatim} By default, cover image is inserted in -\texttt{\textless{}div class="cover-image"\textgreater{}} element, you +\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. @@ -225,16 +232,17 @@ Add item to \texttt{\textless{}manifest\textgreater{}} section in the \Configure{xmlns}{prefix}{uri} \end{verbatim} -Add xml name space to \texttt{xhtml} files. Useful in \texttt{EPUB 3} +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} +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\}}] +\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\}}] @@ -243,16 +251,36 @@ Add file to the \texttt{\textless{}guide\textgreater{}} section in 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}. +deprecated in \texttt{EPUB\ 3}. \end{description} -\subsection{Build files}\label{build-files} +\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. -\section{Troubleshooting}\label{troubleshooting} +\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. @@ -270,7 +298,8 @@ 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} +\hypertarget{fontspec}{% +\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 @@ -306,7 +335,8 @@ 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} +\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 @@ -319,11 +349,12 @@ Type epubcheck filename.epub \end{verbatim} +\hypertarget{common-validation-issues}{% \subsubsection{Common validation -issues:}\label{common-validation-issues} +issues:}\label{common-validation-issues}} \begin{itemize} -\itemsep1pt\parskip0pt\parsep0pt +\tightlist \item WARNING: filename.epub: item (OEBPS/foo.boo) exists in the zip file, but is not declared in the OPF file @@ -333,13 +364,13 @@ 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. + 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} |