summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2023-03-03 21:32:09 +0000
committerKarl Berry <karl@freefriends.org>2023-03-03 21:32:09 +0000
commit0fb6686a392b4ff23b4e40595b22119105fdc13a (patch)
tree102c1e6bc2972b6be4ca61d8d063857033b4a9d3 /Master/texmf-dist/doc/support
parent54edef3568ebd2314ba3ee15176b5c2819fab6df (diff)
tex4ebook (3mar23)
git-svn-id: svn://tug.org/texlive/trunk@66332 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support')
-rw-r--r--Master/texmf-dist/doc/support/tex4ebook/README62
-rw-r--r--Master/texmf-dist/doc/support/tex4ebook/changelog.tex89
-rw-r--r--Master/texmf-dist/doc/support/tex4ebook/readme.tex89
-rw-r--r--Master/texmf-dist/doc/support/tex4ebook/tex4ebook-doc.pdfbin85759 -> 90419 bytes
4 files changed, 220 insertions, 20 deletions
diff --git a/Master/texmf-dist/doc/support/tex4ebook/README b/Master/texmf-dist/doc/support/tex4ebook/README
index 8339341c51a..95c60088eeb 100644
--- a/Master/texmf-dist/doc/support/tex4ebook/README
+++ b/Master/texmf-dist/doc/support/tex4ebook/README
@@ -107,11 +107,6 @@ For example:
values are `default` and `draft`. In `draft` mode, document is compiled
only once, instead of three times.
-`-r,--resolution`
-
-: Resolution of generated images, for example math. It should meet resolution
- of target devices, which is usually about 167 ppi.
-
`-s,--shell-escape`
: Enable shell escape in the `htlatex` run. This is necessary for the execution of the external
@@ -119,7 +114,7 @@ For example:
`-t,--tidy`
-: process output html files with `HTML tidy` command^[It needs to be installed separately].
+: clean-up output HTML files using the `HTML tidy` command^[if it is available on your system].
`-x,--xetex`
@@ -256,8 +251,26 @@ Remarks:
equivalent HTML code needs to be inserted. `UTF8` is not recognized at that place.
- `UTF8` characters may be used in the `OpfMetadata` sections.
+## \TeX4ht options
+
+\TeX4ht supports lot of options, that change produced HTML code without need to
+use configurations. Their list is available in the [\TeX4ht
+documentation](https://www.kodymirus.cz/tex4ht-doc/texfourhtOptions.html).
+You can pass options to `tex4ebook` in the argument that follows filename:
+
+ tex4ebook filename.tex "option1,option2"
+
+Alternatively, they can be put in the `\Preamble` command in the config file:
+
+ \Preamble{xhtml,option1,option2}
+
+### Options provided by `tex4ebook`
+`no-cut`
+: By default `tex4ebook` splits document to separate HTML pages on `\chapter` command when it is available.
+ Othervise, it splits on `\section`. This can be changed using the `\CutAt` command or numeric options, but
+ you need to use the `no-cut` option to prevent fatal error.
## Commands available in the config file
@@ -279,13 +292,42 @@ Remarks:
## Build files
`tex4ebook` uses `make4ht`^[https://github.com/michal-h21/make4ht] as a build
-system. See `make4ht` documentation for details on build files.
+system. It provides support for build files written in Lua. These build files
+can be used to call additional commands, like Bib\TeX\ or Makeindex, post-process
+generated HTML files, change the way how images are created, or to modify
+parameters of the conversion.
+
+Sample build file can look like this:
+
+ if mode=="draft" then
+ Make:htlatex {}
+ else
+ Make:htlatex {}
+ Make:htlatex {}
+ Make:htlatex {}
+ end
+
+ Make:image("png$",
+ "dvipng -bg Transparent -T tight -o ${output} -D 170 -pp ${page} ${source}")
+
+The `mode` variable holds value of the `--mode` argument to `tex4ebook`. The `draft`
+mode is used for faster compilation, it calls LaTeX only once.
+
+The `Make:image` function can configure handling of images created by extraction from the
+DVI file. It can be complex math, TikZ or PSTricks pictures, and so on. The `${<name>}`
+placeholders are filled by `tex4ebook` with parameters like current page number of
+the image DVI file, or output image name.
+
+You can compile your document with a build file using the `-e` option:
+
+ tex4ebook -m draft -e build.lua filename.tex
+
+See `make4ht` documentation for more details on configuration files.
## `.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.
+`tex4ebook` supports a default build file, which is loaded automatically
+without need to use the `-e` option.
### Location
diff --git a/Master/texmf-dist/doc/support/tex4ebook/changelog.tex b/Master/texmf-dist/doc/support/tex4ebook/changelog.tex
index 7eaa4c85ec6..92ec689690e 100644
--- a/Master/texmf-dist/doc/support/tex4ebook/changelog.tex
+++ b/Master/texmf-dist/doc/support/tex4ebook/changelog.tex
@@ -3,6 +3,95 @@
\begin{itemize}
\item
+ 2023/03/02
+
+ \begin{itemize}
+ \tightlist
+ \item
+ released verision \texttt{0.3i}
+ \item
+ check if file with TOC exists before processing.
+ \end{itemize}
+\item
+ 2023/01/12
+
+ \begin{itemize}
+ \tightlist
+ \item
+ added all mimetypes supported in Epub.
+ \end{itemize}
+\item
+ 2023/01/09
+
+ \begin{itemize}
+ \tightlist
+ \item
+ fixed handling of metadata for filenames with accented characters.
+ \end{itemize}
+\item
+ 2022/12/15
+
+ \begin{itemize}
+ \tightlist
+ \item
+ use lower case file extensions for mimetype matching.
+ \end{itemize}
+\item
+ 2022/12/01
+
+ \begin{itemize}
+ \tightlist
+ \item
+ set destinations for \texttt{\textbackslash{}label} used inside of
+ footnotes.
+ \item
+ fixed handling of multiple tables of contents in Epub 3.
+ \end{itemize}
+\item
+ 2022/11/20
+
+ \begin{itemize}
+ \tightlist
+ \item
+ added support for the \texttt{fn-in} option in the Epub 3 output.
+ \end{itemize}
+\item
+ 2022/03/29
+
+ \begin{itemize}
+ \tightlist
+ \item
+ fixed support for \TeX~filenames that contain dot.
+ \item
+ removed spurious comma that was introduced earlier.
+ \end{itemize}
+\item
+ 2022/03/28
+
+ \begin{itemize}
+ \tightlist
+ \item
+ documented the \texttt{no-cut} option.
+ \end{itemize}
+\item
+ 2022/02/23
+
+ \begin{itemize}
+ \tightlist
+ \item
+ extended the documentation about build files.
+ \item
+ deprecated the \texttt{-\/-resolution} CLI argument.
+ \end{itemize}
+\item
+ 2022/02/22
+
+ \begin{itemize}
+ \tightlist
+ \item
+ print \texttt{\textbackslash{}subsubsection} in the Epub TOC.
+ \end{itemize}
+\item
2022/02/18
\begin{itemize}
diff --git a/Master/texmf-dist/doc/support/tex4ebook/readme.tex b/Master/texmf-dist/doc/support/tex4ebook/readme.tex
index 52982d65c45..e144238178a 100644
--- a/Master/texmf-dist/doc/support/tex4ebook/readme.tex
+++ b/Master/texmf-dist/doc/support/tex4ebook/readme.tex
@@ -115,15 +115,12 @@ 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 the \texttt{htlatex} run. This is necessary for
the execution of the 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}.
+clean-up output HTML files using the \texttt{HTML\ tidy}
+command\footnote{if it is available on your system}.
\item[\texttt{-x,-\/-xetex}]
Use xelatex for document compilation
\item[\texttt{-v,-\/-version}]
@@ -304,6 +301,41 @@ Remarks:
sections.
\end{itemize}
+\hypertarget{ht-options}{%
+\subsection{\texorpdfstring{\TeX4ht
+options}{4ht options}}\label{ht-options}}
+
+\TeX4ht supports lot of options, that change produced HTML code without
+need to use configurations. Their list is available in the
+\href{https://www.kodymirus.cz/tex4ht-doc/texfourhtOptions.html}{\TeX4ht
+documentation}. You can pass options to \texttt{tex4ebook} in the
+argument that follows filename:
+
+\begin{verbatim}
+tex4ebook filename.tex "option1,option2"
+\end{verbatim}
+
+Alternatively, they can be put in the \texttt{\textbackslash{}Preamble}
+command in the config file:
+
+\begin{verbatim}
+\Preamble{xhtml,option1,option2}
+\end{verbatim}
+
+\hypertarget{options-provided-by-tex4ebook}{%
+\subsubsection{\texorpdfstring{Options provided by
+\texttt{tex4ebook}}{Options provided by tex4ebook}}\label{options-provided-by-tex4ebook}}
+
+\begin{description}
+\item[\texttt{no-cut}]
+By default \texttt{tex4ebook} splits document to separate HTML pages on
+\texttt{\textbackslash{}chapter} command when it is available.
+Othervise, it splits on \texttt{\textbackslash{}section}. This can be
+changed using the \texttt{\textbackslash{}CutAt} command or numeric
+options, but you need to use the \texttt{no-cut} option to prevent fatal
+error.
+\end{description}
+
\hypertarget{commands-available-in-the-config-file}{%
\subsection{Commands available in the config
file}\label{commands-available-in-the-config-file}}
@@ -328,16 +360,53 @@ deprecated in \texttt{EPUB\ 3}.
\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.
+as a build system. It provides support for build files written in Lua.
+These build files can be used to call additional commands, like
+Bib\TeX~or Makeindex, post-process generated HTML files, change the way
+how images are created, or to modify parameters of the conversion.
+
+Sample build file can look like this:
+
+\begin{verbatim}
+if mode=="draft" then
+ Make:htlatex {}
+else
+ Make:htlatex {}
+ Make:htlatex {}
+ Make:htlatex {}
+end
+
+Make:image("png$",
+"dvipng -bg Transparent -T tight -o ${output} -D 170 -pp ${page} ${source}")
+\end{verbatim}
+
+The \texttt{mode} variable holds value of the \texttt{-\/-mode} argument
+to \texttt{tex4ebook}. The \texttt{draft} mode is used for faster
+compilation, it calls LaTeX only once.
+
+The \texttt{Make:image} function can configure handling of images
+created by extraction from the DVI file. It can be complex math, TikZ or
+PSTricks pictures, and so on. The
+\texttt{\$\{\textless{}name\textgreater{}\}} placeholders are filled by
+\texttt{tex4ebook} with parameters like current page number of the image
+DVI file, or output image name.
+
+You can compile your document with a build file using the \texttt{-e}
+option:
+
+\begin{verbatim}
+tex4ebook -m draft -e build.lua filename.tex
+\end{verbatim}
+
+See \texttt{make4ht} documentation for more details on configuration
+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.
+\texttt{tex4ebook} supports a default build file, which is loaded
+automatically without need to use the \texttt{-e} option.
\hypertarget{location}{%
\subsubsection{Location}\label{location}}
diff --git a/Master/texmf-dist/doc/support/tex4ebook/tex4ebook-doc.pdf b/Master/texmf-dist/doc/support/tex4ebook/tex4ebook-doc.pdf
index 7e8386af7a7..bbc6b2da3fd 100644
--- a/Master/texmf-dist/doc/support/tex4ebook/tex4ebook-doc.pdf
+++ b/Master/texmf-dist/doc/support/tex4ebook/tex4ebook-doc.pdf
Binary files differ