summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/tex4ebook/readme.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support/tex4ebook/readme.tex')
-rw-r--r--Master/texmf-dist/doc/support/tex4ebook/readme.tex103
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}