diff options
author | Karl Berry <karl@freefriends.org> | 2023-03-03 21:32:09 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2023-03-03 21:32:09 +0000 |
commit | 0fb6686a392b4ff23b4e40595b22119105fdc13a (patch) | |
tree | 102c1e6bc2972b6be4ca61d8d063857033b4a9d3 /Master/texmf-dist/doc/support | |
parent | 54edef3568ebd2314ba3ee15176b5c2819fab6df (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/README | 62 | ||||
-rw-r--r-- | Master/texmf-dist/doc/support/tex4ebook/changelog.tex | 89 | ||||
-rw-r--r-- | Master/texmf-dist/doc/support/tex4ebook/readme.tex | 89 | ||||
-rw-r--r-- | Master/texmf-dist/doc/support/tex4ebook/tex4ebook-doc.pdf | bin | 85759 -> 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 Binary files differindex 7e8386af7a7..bbc6b2da3fd 100644 --- a/Master/texmf-dist/doc/support/tex4ebook/tex4ebook-doc.pdf +++ b/Master/texmf-dist/doc/support/tex4ebook/tex4ebook-doc.pdf |