tex4ebook (3mar23)

git-svn-id: svn://tug.org/texlive/trunk@66332 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 52 insertions, 10 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