make4ht (1nov19)

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

5 files changed, 1796 insertions, 1000 deletions

diff --git a/Master/texmf-dist/doc/support/make4ht/README b/Master/texmf-dist/doc/support/make4ht/README
index a99a108d691..df148332394 100644
--- a/Master/texmf-dist/doc/support/make4ht/README
+++ b/Master/texmf-dist/doc/support/make4ht/README
@@ -2,93 +2,209 @@
 
 # Introduction
 
-`make4ht` is a simple build system for `tex4ht`, \TeX\ to XML converter. It provides a command line tool
-that drive the conversion process. It also provides a library which can be used to create
-customized conversion tools. An example of such conversion tool is
-[tex4ebook](https://github.com/michal-h21/tex4ebook) for conversion of \TeX\ to
+`make4ht` is a build system for \TeX4ht, \TeX\ to XML converter. It provides a command line tool
+that drives the conversion process. It also provides a library that can be used to create
+customized conversion tools. An example of such a tool is
+[tex4ebook](https://github.com/michal-h21/tex4ebook), a tool for conversion from \TeX\ to
 ePub and other e-book formats.
 
 
-## How it works
+The basic conversion from \LaTeX\ to `HTML` using `make4ht` can be executed using the following command:
 
-### The issues with default `tex4ht` conversion commands
+    $ make4ht filename.tex
 
+It will produce a file named `filename.html` if the compilation goes without fatal errors.
 
-`tex4ht` system supports several output formats, most notably `XHTML`, `HTML 5` and `ODT`. 
-The conversion can be invoked using several commands. These commands invoke LaTeX\ or Plain TeX 
-with special instructions to load `tex4ht.sty` package. The \TeX\ run produces special `DVI` file 
-which contains the code for desired output format. Produced `DVI` file is then processed and 
-desired output files are created.
 
-The basic command provided by `tex4ht` is named `htlatex`. It  compiles \LaTeX\  
+# Command line options {#clioptions}
+\label{sec:clioptions}
+
+    make4ht - build system for TeX4ht
+    Usage:
+    make4ht [options] filename ["tex4ht.sty op." "tex4ht op." 
+         "t4ht op" "latex op"]
+    -a,--loglevel (default status) Set log level.
+                possible values: debug, info, status, warning, error, fatal
+    -b,--backend (default tex4ht) Backend used for xml generation.
+         possible values: tex4ht or lua4ht
+    -c,--config (default xhtml) Custom config file
+    -d,--output-dir (default "")  Output directory
+    -e,--build-file (default nil)  If build filename is different 
+         than `filename`.mk4
+    -f,--format  (default nil)  Output file format
+    -j,--jobname (default nil)  Set the jobname
+    -l,--lua  Use lualatex for document compilation
+    -m,--mode (default default) Switch which can be used in the makefile
+    -n,--no-tex4ht  Disable DVI file processing with tex4ht command
+    -s,--shell-escape Enables running external programs from LaTeX
+    -u,--utf8  For output documents in utf8 encoding
+    -x,--xetex Use xelatex for document compilation
+    -v,--version  Print version number
+    <filename> (string) Input filename
+
+
+It is still possible to invoke `make4ht` in the same way as is invoked `htlatex`:
+
+    $ make4ht filename "customcfg, charset=utf-8" "-cunihtf -utf8" "-dfoo"
+
+Note that this will not use `make4ht` routines for the output directory handling. 
+See section \ref{sec:output-dir} for more information about this issue.
+To use these routines, change the previous listing to:
+
+    $ make4ht -d foo filename "customcfg, charset=utf-8" "-cunihtf -utf8"
+
+This call has the same effect as the following:
+
+    $ make4ht -u -c customcfg -d foo filename
+
+
+Output directory doesn't have to exist, it will be created automatically. 
+Specified path can be relative to the current directory, or absolute:
+
+    $ make4ht -d use/current/dir/ filename
+    $ make4ht -d ../gotoparrentdir filename
+    $ make4ht -d ~/gotohomedir filename
+    $ make4ht -d c:\documents\windowspathsareworkingtoo filename
+
+The short options that don't take parameters can be collapsed:
+
+
+    $ make4ht -ulc customcfg -d foo filename
+
+
+To pass output from the other commands to `make4ht` use the `-` character as a
+filename. It is best to use this feature together with the `--jobname` or `-j`
+option.
+
+    $ cat hello.tex | make4ht -j world -
+
+By default, `make4ht` tries to be quiet, so it hides most of the command line
+messages and the output from the executed commands. It will display only status
+messages, warnings and errors. The logging level can be selected using the
+`--loglevel` or `-a` options. If the compilation fails, it may be useful to display more 
+information using the `info` or `debug` levels. 
+
+
+    $ make4ht -a debug faulty.tex
+
+
+
+# Why `make4ht`? -- `htlatex` issues
+
+
+\TeX4ht\ system supports several output formats, most notably `XHTML`, `HTML 5`
+and `ODT`, but it also supports `TEI` or `Docbook`.
+
+The conversion can be invoked using several scripts, which are distributed with \TeX4ht.
+They differ in parameters passed to the underlying commands.
+
+These scripts invoke \LaTeX\ or Plain \TeX\ with special instructions to load
+the `tex4ht.sty` package. The \TeX\ run produces a special `DVI` file 
+that contains the code for the desired output format. The produced `DVI` file
+is then processed using the `tex4ht` command, which in conjunction with the
+`t4ht` command produces the desired output files.
+
+## Passing command line arguments
+
+The basic conversion script provided by \TeX4ht\ system is named `htlatex`. It  compiles \LaTeX\  
 files to `HTML` with this command sequence:
 
-    latex $latex_options 'code for loading tex4ht.sty \input{filename}'
-    latex $latex_options 'code for loading tex4ht.sty \input{filename}'
-    latex $latex_options 'code for loading tex4ht.sty \input{filename}'
-    tex4ht $tex4ht_options filename
-    t4ht $t4ht_options filename
+    $ latex $latex_options 'code for loading tex4ht.sty \input{filename}'
+    $ latex $latex_options 'code for loading tex4ht.sty \input{filename}'
+    $ latex $latex_options 'code for loading tex4ht.sty \input{filename}'
+    $ tex4ht $tex4ht_options filename
+    $ t4ht $t4ht_options filename
 
 The options for various parts of the system can be passed on the command line:
 
-    htlatex filename "tex4ht.sty options" "tex4ht_options" "t4ht_options" "latex_options"
+    $ htlatex filename "tex4ht.sty options" "tex4ht_options" "t4ht_options" "latex_options"
 
 For basic `HTML` conversion it is possible to use the most basic invocation:
 
-    htlatex filename.tex
+    $ htlatex filename.tex
 
-It can be much more involved for `HTML 5` output in `UTF-8` encoding:
+It can be much more involved for the `HTML 5` output in `UTF-8` encoding:
 
-    htlatex filename.tex "xhtml,html5,charset=utf-8" "-cmozhtf -utf8"
+    $ htlatex filename.tex "xhtml,html5,charset=utf-8" " -cmozhtf -utf8"
 
 `make4ht` can simplify it:
 
-    make4ht -uf html5 filename.tex
+    $ make4ht -u filename.tex
+
+The `-u` option requires the `UTF-8` encoding. `HTML 5` is used as the default
+output format by `make4ht`.
+
+More information about the command line arguments can be found in section
+\ref{sec:clioptions}.
+
+
+## Compilation sequence
 
-Another issue is the fixed compilation order and hard-coded number of LaTeX invocations.
+`htlatex` has a fixed compilation order and a hard-coded number of \LaTeX\ invocations. 
 
-When you need to run a program which interact with LaTeX, such as `Makeindex`
-or `Bibtex`, you need to create a new script based on `htlatex`, or run
-`htlatex` twice, which means that LaTeX will be invoked six times. 
-This can lead to significantly long compilation times. `make4ht` provides build files and
-extensions, which can be used for interaction with external tools.
+It is not possible to execute additional commands during the compilation.
+When we want to run a program that interacts with \LaTeX, such as `Makeindex`
+or `Bibtex`, we have two options. The first option is to create a new script based on
+`htlatex` and add the wanted commands to the modified script. The second option
+is to execute `htlatex`, then the additional and then `htlatex` again. The
+second option means that \LaTeX\ will be invoked six times, as each call to
+`htlatex` executes three calls to \LaTeX. This can lead to significantly long
+compilation times. 
 
-It is also possible to have several compilation modes. When you just add new text to a document, 
-which doesn't contain cross-references, don't add new stuff to the table of contents, etc., 
-it is possible to use the `draft` mode which will invoke LaTeX only once. It
-can save quite a lot of the compilation time:
+`make4ht` provides a solution for this issue using a build file, or extensions.
+These can be used for interaction with external tools.
 
-    make4ht -um draft -f html5 filename.tex
+`make4ht`  also provides compilation modes, which enables to select commands that
+should be executed using a command line option.
 
-There are also issues with a behaviour of the `t4ht` application. It reads file
-`filename.lg`, generated by `tex4ht`, where are instructions about generated
-files, `CSS` instructions, calls to external applications, instructions for
-image conversions etc. It can be instructed to copy generated files to some
-output directory, but it doesn't preserve directory structure, so when you
-have images in a subdirectory, they will be copied to the output directory.
+There is a built-in `draft` mode, which invokes \LaTeX\ only once, instead of
+the default three invocations.  It is useful for the compilations of the
+document before its final stage, when it is not important that  all
+cross-references work. It can save quite a lot of the compilation time:
+
+    $ make4ht -um draft filename.tex
+
+More information about the build files can be found in section \ref{sec:buildfiles}.
+
+## Handling of the generated files
+\label{sec:output-dir}
+
+There are also issues with the behavior of the `t4ht` application. It reads the 
+`.lg` file generated by the `tex4ht` command. This file contains
+information about the generated files, `CSS` instructions, calls to the external
+applications, instructions for image conversions, etc. 
+
+
+`t4ht` can be instructed to copy the generated files to an output directory, but
+it doesn't preserve the directory structure. When the images are placed in a  
+subdirectory, they will be copied to the output directory, losing the directory structure.
 Links will be pointing to a non-existing subdirectory. The following command
 should copy all output files to the correct destinations.
 
-    make4ht -d outputdir filename.tex
+    $ make4ht -d outputdir filename.tex
+
+## Image conversion and post-processing of the generated files
+
+\TeX4ht\ can convert parts of the document to images. This is useful 
+for diagrams or complicated math, for example.
 
-The image conversion is configured in the
-[env file](http://www.tug.org/applications/tex4ht/mn35.html#index35-73001),
-which has really strange syntax based and the rules are 
-[os dependent](http://www.tug.org/applications/tex4ht/mn-unix.html#index27-69005).
+By default, the image conversion is configured in a
+[`.env` file](http://www.tug.org/applications/tex4ht/mn35.html#index35-73001).
+It has a bit of strange syntax,  with 
+[operating system dependent](http://www.tug.org/applications/tex4ht/mn-unix.html#index27-69005) rules.
 `make4ht` provides simpler means for the image conversion in the build files.
+It is possible to change the image conversion parameters without a need to modify the `.env` file.
+The process is described in section \ref{sec:imageconversion}.
+
+It is also possible to post-process the generated output files. The post-processing can be done
+either using external programs such as `XSLT` processors and `HTML Tidy` or
+using `Lua` functions. More information can be found in section \ref{sec:postprocessing}.
 
-With `make4ht` build files, we have simple mean to fix these issues. We can
-change image conversion parameters without the need to modify the `env file`,
-or execute actions on the output files. These actions can be either external
-programs such as `xslt` processors or `HTML tidy` or `Lua` functions.
 
-The idea is to make system controlled by a build file. Because `Lua`
-interpreter is included in modern TeX distributions and `Lua` is ideal language
-for such task, it was chosen as language in which the build scripts are written.
 
 # Output file formats and extensions
 
-The default output format used by `make4ht` is `html5`. Different
+The default output format used by `make4ht` is `html5`. A different
 format can be requested using the `--format` option. Supported formats are:
 
  - `xhtml`
@@ -107,22 +223,10 @@ may post-process the output files or request additional commands for the compila
 The extensions can be enabled or disabled by appending `+EXTENSION` or `-EXTENSION` after
 the output format name:
 
-     make4ht -uf html5+tidy filename.tex
+     $ make4ht -uf html5+tidy filename.tex
 
 Available extensions:
 
-latexmk_build
-
-:    use `Latexmk` for \LaTeX\ compilation.
-
-tidy
-
-:    clean the `HTML` files using the `tidy` command.
-
-dvisvgm_hashes
-
-:    efficient generation of SVG pictures using Dvisvgm. It can utilize
-multiple processor cores and generates only changed images.
 
 common\_filters
 
@@ -131,13 +235,22 @@ common\_filters
 common\_domfilters
 
 :    clean the HTML file using DOM filters. It is more powerful than
-`common_filters`. Used DOM filters are `fixinlines`, `idcolons` and
-`joincharacters`.
+`common_filters`. Used DOM filters are `fixinlines`, `idcolons`,
+`joincharacters`, and `tablerows`.
+
+dvisvgm\_hashes
+
+:    efficient generation of SVG pictures using Dvisvgm. It can utilize
+multiple processor cores and generates only changed images.
 
 join\_colors
 
 :    load the `joincolors` domfilter for all HTML files.
 
+latexmk\_build
+
+:    use [Latexmk](https://ctan.org/pkg/latexmk?lang=en) for the \LaTeX\ compilation.
+
 mathjaxnode
 
 :    use [mathjax-node-page](https://github.com/pkra/mathjax-node-page/) to
@@ -146,21 +259,35 @@ mathjaxnode
 
 odttemplate
 
-:    automatically load the `odttemplate` filter.
+:    it automatically loads the `odttemplate` filter (page \pageref{sec:odttemplate}).
+
+preprocess\_input 
+
+:     compilation of the formats
+      supported by [Knitr](https://yihui.name/knitr/) (`.Rnw`, `.Rtex`, `.Rmd`, `.Rrst`) 
+      and also Markdown and reStructuredText formats. It requires
+[R](https://www.r-project.org/) + [Knitr](https://yihui.name/knitr/)
+installation, it requires also [Pandoc](https://pandoc.org/) for formats based on Markdown or
+reStructuredText.
 
 staticsite
 
-:    build the document in form suitable for static site generators like [Jekyll](https://jekyllrb.com/).
+:    build the document in a form suitable for static site generators like [Jekyll](https://jekyllrb.com/).
+
+tidy
+
+:    clean the `HTML` files using the `tidy` command.
 
 # Build files
+\label{sec:buildfiles}
 
-`make4ht` supports build files. These are `Lua` scripts which can adjust
-the build process. You can request external applications like `bibtex` or `makeindex`,
+`make4ht` supports build files. These are `Lua` scripts that can adjust
+the build process. They can request external applications like `BibTeX` or `Makeindex`,
 pass options to the commands, modify the image conversion process, or post-process the
 generated files.
 
 `make4ht` tries to load default build file named as `filename + .mk4 extension`.
-You can choose different build file with `-e` or `--build-file` command line
+It is possible to select a different build file with `-e` or `--build-file` command line
 option.
 
 Sample build file:
@@ -168,185 +295,205 @@ Sample build file:
     Make:htlatex()
     Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}")
 
-`Make:htlatex()` is preconfigured command for calling LaTeX with `tex4ht`
-loaded on the input file. In this case, it will be called  one time. After
-compilation, the `tidy` command is executed on the output `HTML` file.
+`Make:htlatex()` is preconfigured command for calling \LaTeX\ with the `tex4ht.sty` package
+loaded. In this example, it will be executed  only once. After the 
+compilation, the `tidy` command is executed on the output `HTML` files.
 
-Note that you don't have to call `tex4ht` and `t4ht` commands explicitly in the
+Note that it is not necessary to call `tex4ht` and `t4ht` commands explicitly in the
 build file, they are called automatically. 
 
 ## User commands
 
-You can add more commands like `Make:htlatex` using `Make:add` command:
+It is possible to add more commands like `Make:htlatex` using the `Make:add` command:
 
-    Make:add("name", "command", {parameters}, repetition)
+    Make:add("name", "command", {settings table}, repetition)
 
-The `name` and `command` parameters are required, rest of the parameters are optional.
+This defines the `name` command, which can be then executed using `Make:name()`
+command in the build file. 
 
-This defines `name` command, which can be then executed as `Make:name()` command.
+The `name` and `command` parameters are required, the rest of the parameters are optional.
 
-### Provided commands
+The defined command receives a table with settings as a parameter at the call time. 
+The default settings are provided by `make4ht`. Additional settings can be
+declared in the `Make:add` commands, user can also override the default settings
+when the command is executed in the build file:
 
-`Make:htlatex`
+    Make:name({hello="world"})
 
-:    One call to TeX engine with special configuration for `tex4ht` loading.
+More information about settings, including the default settings provided by
+`make4ht`,  can be found in section \ref{sec:settings} on page
+\pageref{sec:settings}.
 
-`Make:latexmk`
 
-:    Use `Latexmk` for the document compilation. `tex4ht` will be loaded automatically.
+### The `command` function
+\label{sec:commandfunction}
 
-`Make:tex4ht`
+The `command` parameter can be either a string template or function:
 
-:    Process the `DVI` file and creates the output files.
+    Make:add("text", "echo hello, input file: ${input}")
 
-`Make:t4ht`
+The template can get a variable value from the parameters table using a
+`${var_name}` placeholder. Templates are executed using the operating system, so
+they should invoke existing OS commands. 
 
-:    Creates the CSS file.
 
 
-### Command function
 
-The `command` parameter can be either string template or function:
 
-    Make:add("text", "echo hello, input file: ${input}")
-    Make:add("function", function(params) 
+### The `settings table` table
+
+
+The `settings table` parameter is optional. If it is present, it should be
+a table with new settings available in the command. It can also override the default
+`make4ht` settings for the defined command.
+
+    Make:add("sample_function", function(params) 
       for k, v in pairs(params) do 
         print(k..": "..v) 
       end, {custom="Hello world"}
     )
 
-The template can get variable value from the parameters table using a
-`${var_name}` placeholder. Templates are executed using operating system, so
-they should invoke existing OS commands. Function commands may execute system
-commands using `os.execute` function.
-
-
-### Parameters table
 
-`parameters` parameter is optional, it can be table or `nil` value, which
-should be used if you want to use the `repetition` parameter, but don't want to
-modify the parameters table. 
+### Repetition
 
-The table with default parameters is passed to all commands, they can be accessed from command functions
-or templates. When you specify your own parameters in the command definition, these additional
-parameters are added to the default parameters table for this particular
-command. You can override the default parameters in the parameters table.
+The `repetition` parameter  specifies the maximum number of executions of the
+particular command.  This is used for instance for `tex4ht` and `t4ht`
+commands, as they should be executed only once in the compilation. They would
+be executed multiple times when they are included in the build file, as they
+are called by `make4ht` by default. Because these commands allow only one
+`repetition`, the second execution is blocked.
 
+### Expected exit code
 
+You can set the expected exit code from a command with a `correct_exit` key in the
+settings table. The compilation will be terminated when the command returns a
+different exit code. 
 
-The default parameters are following:
+    Make:add("biber", "biber ${input}", {correct_exit=0})
 
-`htlatex`
+Commands that execute lua functions can return the numerical values using the `return` statement.
 
-:     used compiler
 
-`input`
+This mechanism isn't used for \TeX, because it doesn't differentiate between fatal and non-fatal errors. 
+It returns the same exit code in all cases. Because of this, log parsing is used for a fatal error detection instead.
+Error code value `1` is returned in the case of a fatal error, `0` is used
+otherwise. The `Make.testlogfile` function can be used in the build file to
+detect compilation errors in the TeX log file.
 
-:    it is output file name in fact
 
-`tex_file`
+## Provided commands
 
-:    input TeX file
+`Make:htlatex`
 
-`latex_par`
+:    One call to the TeX engine with special configuration for loading of the `tex4ht.sty` package.
 
-:    parameters to `latex`
+`Make:latexmk`
 
-`packages`
+:    Use `Latexmk` for the document compilation. `tex4ht.sty` will be loaded automatically.
 
-:    insert additional LaTeX code which is inserted before `\documentclass`.
-     Useful for passing options to packages or additional packages loading
+`Make:tex4ht`
 
-`tex4ht_sty_par`
+:    Process the `DVI` file and create output files.
 
-:    parameters to `tex4ht.sty`
+`Make:t4ht`
 
-`tex4ht_par`
+:    Create the CSS file and generate images.
 
-:     parameters to the `tex4ht` application
+`Make:biber`
 
-`t4ht_par`
+:    Process bibliography using the `biber` command.
 
-:    parameters to the `t4ht` application
+`Make:bibtex`
 
-`outdir`
+:    Process bibliography using the `bibtex` command.
 
-:    the output directory
+`Make:xindy`
 
-`repetition`
+:    Generate index using Xindy index processor.
 
-:    limit number of command execution.
+`Make:makeindex`
 
-`correct_exit`
+:    Generate index using the Makeindex command.
 
-:    expected `exit code` from the command. The compilation will be terminated
-     if the command `exit code` is different.
+`Make:xindex`
 
+:    Generate index using the Xindex command.
 
-### Repetition
 
-Repetition is number which specifies a maximal number of executions of the
-particular command.  This is used for instance for `tex4ht` and `t4ht`
-commands, as they should be executed only once in the compilation. They would
-be executed multiple times if you include them in the build file because they
-are called by `make4ht` by default. Because these commands allow only one
-`repetition`, the second execution will be blocked.
+## File matches
+\label{sec:postprocessing}
 
-### Expected exit code
+Another type of action that can be specified in the build file is
+`Make:match`.  It can be used to post-process  the generated files:
 
-You can set the expected exit code from a command with a `correct_exit` key in the
-parameters table. The compilation will be stopped when the command returns a
-different exit code. 
+    Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}")
 
-This mechanism isn't used for LaTeX (for all TeX engines and formats, in
-fact), because it doesn't differentiate between fatal and non-fatal errors, and
-it returns the same exit code in all cases. Log parsing is used because of
-that, error code `1` is returned in the case of fatal error, `0` is used
-otherwise. The `Make.testlogfile` function can be used in the build file to
-detect compilation errors in the TeX log file.
+The above example will clean all output `HTML` files using the `tidy` command.
 
-## File matches
+The `Make:match` action tests output filenames using a `Lua` pattern matching function.  
+It executes a command or a function, specified in the second argument, on files
+whose filenames match the pattern. 
 
-Another type of action which can be specified in the build file is
-`match`.  It can be called on the generated files:
+The commands to be executed can be specified as strings. They can contain
+`${var_name}` placeholders, which are replaced with corresponding variables
+from the `settings` table. The templating system was described in 
+subsection \ref{sec:commandfunction}. There is an additional variable
+available in this table, called `filename`. It contains the name of the current
+output file.
 
-    Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}")
 
-It tests output file names with `Lua` pattern matching and on matched items will
-execute a command or a function, specified in the second argument. Commands may be
-specified as strings, the templates will be expanded, `${var_name}` placeholders
-will be replaced with corresponding variables from the `parameters` table,
-described in the previous subsection. One additional variable is available:
-`filename`. It contains the name of the current output file.
+If a function is used instead, it will get two parameters.  The first one is the
+current filename, the second one is the `settings` table. 
 
-The above example will clean all output `HTML` files using the `tidy` command.
+    Make:match("html$", function(filename, settings)
+      print("Post-processing file: ".. filename)
+      print("Available settings")
+      for k,v in pairs(settings)
+        print(k,v)
+      end
+      return true
+   end)
 
-If function is used instead, it will get two parameters.
-The first one is a current filename, the second one
-table with parameters. 
+Multiple post-processing actions can be executed on each filename. The Lua
+action functions can return an exit code. If the exit code is false, the execution
+of the post-processing chain for the current file will be terminated.
 
+### Filters
+\label{sec:filters}
 
+To make it easier to post-process the generated files using the `match`
+actions, `make4ht` provides a filtering mechanism thanks to the
+`make4ht-filter` module. 
 
-### Filters
+The `make4ht-filter` module returns a function that can be used for the filter
+chain building. Multiple filters can be chained into a pipeline. Each filter
+can modify the string that is passed to it from the previous filters. The
+changes are then saved to the processed file. 
 
-Some default `match` actions which can be used are available from  the
-`make4ht-filter` module.  It contains some functions which are useful for
-fixing some `tex4ht` bugs or shortcomings.
+Several built-in filters are available, it is also possible to create new ones.
 
-Example:
+Example that use only the built-in filters:
 
     local filter = require "make4ht-filter"
     local process = filter{"cleanspan", "fixligatures", "hruletohr"}
     Make:htlatex()
+    Make:match("html$",process)
+
+Function `filter` accepts also function arguments, in this case this function
+takes file contents as a parameter and modified contents are returned.
+
+Example with custom filter:
+
+    local filter  = require "make4ht-filter"
+    local changea = function(s) return s:gsub("a","z") end
+    local process = filter{"cleanspan", "fixligatures", changea}
     Make:htlatex()
     Make:match("html$",process)
 
-The `make4ht-filter` module return a function which can be used for the filter
-chain building. Multiple filters can be chained, each of them can modify the string
-which was modified by the previous filters. The changes are then saved to the
-processed file.
+In this example, spurious span elements are joined, ligatures are decomposed,
+and then all letters "a" are replaced with "z" letters.
 
-Built-in filters are:
+Built-in filters are the following:
 
 cleanspan
 
@@ -363,19 +510,18 @@ fixligatures
 hruletohr
 
 :   `\hrule` commands are translated to series of underscore characters
-    by `tex4ht`, this filter translate these underscores to `<hr>` elements
+    by \TeX4ht, this filter translates these underscores to `<hr>` elements
 
 entites
 
-:    convert prohibited named entities to numeric entities (currently, only
-     `&nbsp;`, as it causes validation errors, and `tex4ht` is producing it
-     sometimes)
+:    convert prohibited named entities to numeric entities (only
+     `&nbsp;` currently).
 
 fix-links
 
 :    replace colons in local links and `id` attributes with underscores. Some
      cross-reference commands may produce colons in internal links, which results in
-     validation error.
+     a validation error.
 
 mathjaxnode
 
@@ -388,36 +534,24 @@ odttemplate
 :    use styles from another `ODT` file serving as a template in the current
      document. It works for the `styles.xml` file in the `ODT` file. During
      the compilation, this file is named as `\jobname.4oy`.
+     \label{sec:odttemplate}
 
 staticsite
 
-:    create HTML files in format suitable for static site generators such as [Jekyll](https://jekyllrb.com/)
+:    create HTML files in a format suitable for static site generators such as [Jekyll](https://jekyllrb.com/)
 
 svg-height
 
 :    some  SVG images produced by `dvisvgm` seem to have wrong dimensions. This filter
      tries to set the correct image size.
 
-Function `filter` accepts also function arguments, in this case this function
-takes file contents as a parameter and modified contents are returned.
-
-Example:
-
-    local filter  = require "make4ht-filter"
-    local changea = function(s) return s:gsub("a","z") end
-    local process = filter{"cleanspan", "fixligatures", changea}
-    Make:htlatex()
-    Make:htlatex()
-    Make:match("html$",process)
-
-In this example, spurious span elements are joined, ligatures are decomposed,
-and then all letters 'a' are replaced with 'z' letters.
 
 ### DOM filters
 
-DOM filters use the [`LuaXML`](https://ctan.org/pkg/luaxml) library to modify
+DOM filters are variants of filters that use the
+[`LuaXML`](https://ctan.org/pkg/luaxml) library to modify
 directly the XML object. This enables more powerful
-operations than the regex based filters from the previous section. 
+operations than the regex-based filters from the previous section. 
 
 Example:
 
@@ -431,7 +565,11 @@ Available DOM filters:
 aeneas
 
 :  [Aeneas](https://www.readbeyond.it/aeneas/) is a tool for automagical synchronization of text and audio.
-   This filter modifies the HTML code to support the synchronization.
+   This filter modifies the HTML code to support synchronization.
+
+collapsetoc
+
+:  collapse table of contents to contain only top-level sectioning level and sections on the current page.
 
 fixinlines
 
@@ -443,296 +581,350 @@ idcolons
 
 joincharacters
 
-:  join consecutive `<span>` or `<mn>` elements.
+:  join consecutive `<span>` or `<mn>` elements. This DOM filter supersedes the `cleanspan` filter.
 
 joincolors
 
-:  many `<span>` elements with unique `id` attribute are created when \LaTeX\ colors are being used in the document.
-   CSS rule is added for each of these elements, which may result in
-   substantial grow of the CSS file. This filter replace these rules with a
+:  many `<span>` elements with unique `id` attributes are created when \LaTeX\ colors are being used in the document.
+   A CSS rule is added for each of these elements, which may result in
+   substantial growth of the CSS file. This filter replaces these rules with a
    common one for elements with the same color value.
 
 odtimagesize
 
 :  set correct dimensions for images in the ODT format. It is loaded by default for the ODT output.
 
+odtpartable
+
+:  resolve tables nested inside paragraphs, which is invalid in the ODT format.
+
+tablerows
+
+:  remove spurious rows from HTML tables.
+
 t4htlinks
 
 :  fix hyperlinks in the ODT format.
 
-### make4ht-aeneas-config package
 
-Companion for the `aeneas` DOM filter is the `make4ht-aeneas-config` plugin. It
-can be used to write Aeneas configuration file or execute Aeneas on the
-generated HTML files.
 
-Available functions:
+## Image conversion
+\label{sec:imageconversion}
 
-write\_job(parameters)
+It is possible to convert parts of the \LaTeX\ input as pictures. It can be used
+for preserving the appearance of  math or diagrams, for example. 
 
-:  write Aenas job configuration to `config.xml` file. See the [Aeneas
-   documentation](https://www.readbeyond.it/aeneas/docs/clitutorial.html#processing-jobs)
-   for more information about jobs.
+These pictures are stored in a special `DVI` file, which can be processed by
+a `DVI` to image commands, such as `dvipng` or `dvisvgm`. 
 
-execute(parameters)
+This conversion is normally configured in the `tex4ht.env` file. This file
+is system dependent and it has quite an unintuitive syntax.
+The configuration is processed by the `t4ht` application and the conversion
+command is called for all pictures.
 
-:  execute Aeneas.
+It is possible to disable `t4ht` image processing and configure image
+conversion in the build file using the `image` action:
 
-process\_files(parameters)
+    Make:image("png$",
+    "dvipng -bg Transparent -T tight -o ${output}  -pp ${page} ${source}")
 
-:  process the audio and generated subtitle files.
 
+`Make:image` takes two parameters, a `Lua` pattern to match the image name, and
+the action.
 
-By default, the `smil` file is created. It is assumed that there is audio file
-in `mp3` format named as the TeX file. It is possible to use different formats
-and file names using mapping.
+Action can be either a string template with the conversion command
+or a function that takes a table with parameters as an argument.
 
-The configuration options can be passed directly to the functions or set using
-`filter_settings "aeneas-config" {parameters}` function.
+There are three parameters:
 
+  - `output` - output image filename
+  - `source` - `DVI` file with the pictures
+  - `page`   - page number of the converted image
 
-Available parameters:
+## The `mode` variable
 
+The `mode` variable available in the build process contains 
+contents of the `--mode` command line option.  It can be used to run some commands
+conditionally. For example:
 
-lang 
+     if mode == "draft" then
+       Make:htlatex{} 
+     else
+       Make:htlatex{}
+       Make:htlatex{}
+       Make:htlatex{}
+     end
 
-:  document language. It is interfered from the HTML file, so it is not necessary to set it. 
+In this example (which is the default configuration used by `make4ht`),
+\LaTeX\ is called only once when `make4ht` is called with the `draft` mode:
+    
+    make4ht -m draft filename
 
-map 
+## The `settings` table
+\label{sec:settings}
 
-:  mapping between HTML, audio and subtitle files. More info bellow. 
+It is possible to access the parameters outside commands, file matches
+and image conversion functions. For example, to convert the document to
+the `OpenDocument Format (ODT)`, the following settings can be used. They are
+based on the `oolatex` command:
 
-text\_type 
+    settings.tex4ht_sty_par = settings.tex4ht_sty_par ..",ooffice"
+    settings.tex4ht_par = settings.tex4ht_par .. " ooffice/! -cmozhtf"
+    settings.t4ht_par = settings.t4ht_par .. " -cooxtpipes -coo "
 
-:  type of the input. The `aeneas` DOM filter produces `unparsed` text type.
+(Note that it is possible to use the `--format odt` option
+which is superior to the previous code. This example is intended just as an
+illustration)
 
-id\_sort 
+There are some functions to simplify access to the settings:
 
-:  sorting of id attributes. Default value is `numeric`.
+`set_settings{parameters}`
 
-id\_regex 
+:   overwrite settings with values from a passed table
 
-:  regular expression to parse the id attributes.
+`settings_add{parameters}`
 
-sub\_format 
+:   add values to the current settings 
 
-:  generated subtitle format. Default `smil`.
+`filter_settings "filter name" {parameters}`
 
+:   set settings for a filter
 
-Additional parameters for the job configuration file:
+`get_filter_settings(name)`
 
-- description 
-- prefix 
-- config\_name 
-- keep\_config 
+:   get settings for a filter
 
 
+For example, it is possible to simplify the sample from the previous code listings:
 
-It is possible to generate multiple HTML files from the LaTeX source. For
-example, `tex4ebook` generates separate file for each chapter or section. It is
-possible to set options for each HTML file, in particular names of the
-corresponding audio files. This mapping is done using `map` parameter. 
+    settings_add {
+      tex4ht_sty_par =",ooffice",
+      tex4ht_par = " ooffice/! -cmozhtf",
+      t4ht_par = " -cooxtpipes -coo "
+    }
 
-Example:
+Settings for filters and extensions can be set using `filter_settings`:
 
-    filter_settings "aeneas-config" {
-      map = {
-        ["sampleli1.html"] = {audio_file="sample.mp3"}, 
-        ["sample.html"] = false
-      }
+    
+    filter_settings "test" {
+      hello = "world"
     }
 
-Table keys are the configured file names. It is necessary to insert them as
-`["filename.html"]`, because of Lua syntax rules.
+These settings can be retrieved in the extensions and filters using the `get_filter_settings` function:
 
-This example maps audio file `sample.mp3` to a section subpage. The main HTML
-file, which may contain title and table of contents doesn't have a
-corresponding audio file.
+    function test(input)
+       local options = get_filter_settings("test")
+       print(options.hello)
+       return input
+    end
+       
+### Default settings
 
-Filenames of the sub files corresponds to the chapter numbers, so they are not
-stable when a new chapter is added. It is possible to request file names
-interfered from the chapter titles using the `sec-filename` option or `tex4ht`.
+The default parameters are the following:
 
-Available `map` options:
+`htlatex`
 
+:     used \TeX\ engine
 
-audio\_file 
+`input`
 
-:  the corresponding audio file 
+:    content of `\jobname`, see also the `tex_file` parameter.
 
-sub\_file 
+`interaction`
 
-:  name of the generated subtitle file
+:    interaction mode for the \TeX\ engine. The default value is `batchmode` to
+     suppress user input on compilation errors. It also suppresses most of the \TeX\ 
+     compilation log output. Use the `errorstopmode` for the default behavior.
 
-The following options are same as their counter-parts from the main parameters table and generally don't need to be set:
+`tex_file`
 
-- prefix 
-- file\_desc 
-- file\_id 
-- text\_type 
-- id\_sort
-- id\_prefix 
-- sub\_format 
+:    input \TeX\ filename
 
+`latex_par`
 
-Full example:
+:    command line parameters to the \TeX\ engine
 
+`packages`
 
-    local domfilter = require "make4ht-domfilter"
-    local aeneas_config = require "make4ht-aeneas-config"
-    
-    filter_settings "aeneas-config" {
-      map = {
-        ["krecekli1.xhtml"] = {audio_file="krecek.mp3"}, 
-        ["krecek.xhtml"] = false
-      }
-    }
-    
-    local process = domfilter {"aeneas"}
-    Make:match("html$", process)
+:    additional \LaTeX\ code  inserted before `\documentclass`.
+     Useful for passing options to packages used in the document or to load additional packages.
 
-    if mode == "draft" then
-      aeneas_config.process_files {}
-    else
-      aeneas_config.execute {}
-    end
+`tex4ht_sty_par`
 
+:    options for `tex4ht.sty`
 
+`tex4ht_par`
 
+:     command line options for the `tex4ht` command
 
-## Image conversion
+`t4ht_par`
 
-It is possible to convert parts of LaTeX input to pictures, it is used
-for example for math or diagrams in `tex4ht`. 
+:    command line options for the `t4ht` command
 
-These pictures are stored in a special `dvi` file, which can be processed by
-the `dvi to image` commands. 
+`outdir`
 
-This conversion is normally configured in the `env file`,
-which is system dependent and which has a bit unintuitive syntax.
-This configuration is processed by the `t4ht` application and conversion
-commands are called for all pictures.
+:    the output directory
 
-It is possible to disable `t4ht` image processing and configure image
-conversion in the build file:
+`correct_exit`
 
-    Make:image("png$",
-    "dvipng -bg Transparent -T tight -o ${output}  -pp ${page} ${source}")
+:    expected `exit code` from the command. The compilation will be terminated
+     if the exit code of the executed command has a different value.
 
 
-`Make:image` takes two parameters, pattern to match image name and action.
-Action can be either string template with conversion command,
-or function which takes a table with parameters as an argument.
+# Configuration file {#configfile}
 
-There are three parameters:
+It is possible to globally modify the build settings using the configuration
+file. It is a special version of a build file where the global settings can be set.
 
-  - `output` - output image file name
-  - `source` - `dvi` file with the pictures
-  - `page`   - page number of the converted image
+Common tasks for the configuration file can be a declaration of the new commands,
+loading of the default filters or specification of a default build sequence. 
 
-## The `mode` variable
+One additional functionality not available in the build files are commands for
+enabling and disabling of extensions.
 
-There is global `mode` variable available in the build file. It contains
-contents of the `--mode` command line option.  It can be used to run some commands
-conditionally. For example:
 
-     if mode == "draft" then
-       Make:htlatex{} 
-     else
-       Make:htlatex{}
-       Make:htlatex{}
-       Make:htlatex{}
-     end
+## Location 
 
-In this example (which is the default configuration used by `make4ht`),
-LaTeX is called only once when `make4ht` is called with `draft` mode:
-    
-    make4ht -m draft filename
+The configuration file can be saved either in the
+`$HOME/.config/make4ht/config.lua` file, or in the `.make4ht` file placed in
+the current directory or it's parent directories (up to the `$HOME` directory). 
 
-## The `settings` table
+## Additional commands
 
-You may want to access to the parameters also outside commands, file matches
-and image conversion functions. For example, if you want to convert your file to
-the `OpenDocument Format (ODT)`, you can use the following settings, based on the `oolatex`
-command:
+There are two additional commands:
 
-    settings.tex4ht_sty_par = settings.tex4ht_sty_par ..",ooffice"
-    settings.tex4ht_par = settings.tex4ht_par .. " ooffice/! -cmozhtf"
-    settings.t4ht_par = settings.t4ht_par .. " -cooxtpipes -coo "
+`Make:enable_extension(name)`
 
-There are some functions to ease access to the settings:
+:  require extension
 
-`set_settings{parameters}`
+`Make:disable_extension(name)`
 
-:   overwrite settings with values from a passed table
+:  disable extension
 
-`settings_add{parameters}`
+## Example
 
-:   add values to the current settings 
+The following example of the configuration file adds support for the `biber` command, requires
+`common_domfilters` extension and requires MathML
+output for math.
 
-`filter_settings "filter name" {parameters}`
+    Make:add("biber", "biber ${input}")
+    Make:enable_extension "common_domfilters"
+    settings_add {
+      tex4ht_sty_par =",mathml"
+    }
 
-:   set settings for a filter
+<!--
+# Development
 
-`get_filter_settings(name)`
+## Custom filters
 
-:   get settings for a filter
+## New extensions
 
+## How to add a new output format
 
-Using these functions, it is possible to simplify the settings for the `ODT` format:
+-->
 
-    settings_add {
-      tex4ht_sty_par =",ooffice",
-      tex4ht_par = " ooffice/! -cmozhtf",
-      t4ht_par = " -cooxtpipes -coo "
-    }
+# List of available settings for filters and extensions.
 
-Settings for filters and extensions can be set using `filter_settings`:
+These settings may be set using `filter_settings` function in a build file or in the `make4ht` configuration file.
 
-    
-    filter_settings "test" {
-      hello = "world"
-    }
 
-These settings can be read in the extensions and filters using `get_filter_settings`:
 
-    function test(input)
-       local options = get_filter_settings("test")
-       print(options.hello)
-       return input
-    end
-       
-## List of available settings for filters and extensions.
+## Indexing commands
+
+The indexing commands (like `xindy` or `makeindex`) use some common settings.
+
+idxfile
+
+:    name of the `.idx` file. Default value is `\jobname.idx`.
+
+indfile
+
+:    name of the `.ind` file. Default value is the same as `idxfile` with the file extension changed to `.ind`.
+
+Each indexing command can have some additional settings.
+
+### The `xindy` command
+
+encoding
+
+:    text encoding of the `.idx` file. Default value is `utf8`.
+
+language
+
+:    index language. Default language is English.
+
+modules
+
+:    table with names of additional `Xindy` modules to be used.
+
+### The `makeindex` command
+
+options
 
-These settings may be set using `filter_settings` function.
 
-### The `tidy` extension
+:    additional command line options for the Makeindex command.
+
+### The `xindex` command
+
+options
+
+
+:    additional command line options for the Xindex command.
+
+language
+
+:    document language
+
+## The `tidy` extension
 
 options
 
 :  command line options for the `tidy` command. Default value is `-m -utf8 -w 512 -q`.
 
-### The `fixinlines` dom filter 
+## The `collapsetoc` dom filter
+
+`toc_query` 
+
+:  CSS selector for selecting the table of contents container. 
+
+`title_query`
+
+:  CSS selector for selecting all elements that contain the section ID attribute.
+
+`toc_levels` 
+
+:  table containing a hierarchy of classes used in TOC
+
+Default values:
+
+    filter_settings "collapsetoc" {
+      toc_query = ".tableofcontents",
+      title_query = ".partHead a, .chapterHead a, .sectionHead a, .subsectionHead a",
+      toc_levels = {"partToc", "chapterToc", "sectionToc", "subsectionToc", "subsubsectionToc"}
+    }
+
+## The `fixinlines` dom filter 
 
 inline\_elements
 
-:  table of inline elements which shouldn't be direct descendants of the `body` element. The element names should be table keys, the values should be true.
+:  table of inline elements that shouldn't be direct descendants of the `body` element. The element names should be table keys, the values should be true.
 
 Example
 
     filter_settings "fixinlines" {inline_elements = {a = true, b = true}}
 
-### The `joincharacters` dom filter
+## The `joincharacters` dom filter
 
-charelements 
+charclasses 
 
-:  table of elements which should be joined if several instances with the same value of `class` attribute are side by side.
+:  table of elements that should be concatenated when two or more of such elements with the same value of the `class` attribute are placed one after another.
 
 Example
 
-    filter_settings "joincharacters" { charclases = { span=true, mn = true}}
+    filter_settings "joincharacters" { charclasses = { span=true, mn = true}}
 
-### The `mathjaxnode` filter {#mathjaxsettings}
+## The `mathjaxnode` filter {#mathjaxsettings}
 
 options
 
@@ -746,12 +938,12 @@ Example
 
 cssfilename  
 
-:  `mjpage` puts some CSS code into the HTML pages. `mathjaxnode` extracts this information and saves it to a standalone CSS file. Default CSS filename is `mathjax-chtml.css`
+:  the `mjpage` command puts some CSS code into the HTML pages. `mathjaxnode` extracts this information and saves it to a standalone CSS file. Default CSS filename is `mathjax-chtml.css`
 
 fontdir
 
-:  directory with MathJax font files. This option enables use of local fonts, which
-   is usefull in Epub conversion, for example. The font directory should be
+:  directory with MathJax font files. This option enables the use of local fonts, which
+   is useful in the conversion to ePub, for example. The font directory should be
    sub-directory of the current directory. Only TeX font is supported at the moment.
 
 Example
@@ -761,21 +953,8 @@ Example
       fontdir="fonts/TeX/woff/" 
     }
 
-### The `aeneas` filter
-
-skip\_elements
-
-:  List of CSS selectors that match elements which shouldn't be processed. Default value: `{ "math", "svg"}`.
-
-id\_prefix 
-
-:  prefix used in the ID attribute forming.
-
-sentence\_match 
-
-:  Lua pattern used to match a sentence. Default value: `"([^%.^%?^!]*)([%.%?!]?)"`.
 
-### The `staticsite` filter and extension
+## The `staticsite` filter and extension
 
 site\_root 
 
@@ -783,15 +962,22 @@ site\_root
 
 map
 
-:  table where keys are patterns that match filenames, value contains destination directoryfor matched files, relative to the `site_root` (it is possible to use `..` to swich to parent directory).
+:  a hash table where keys contain patterns that match filenames and values contain
+destination directory for the matched files. The destination directories are
+relative to the `site_root` (it is possible to use `..` to switch to a parent
+directory).
 
 file\_pattern 
 
-:  pattern used for filename generation. It is possible to use string templates and format strings for `os.date` function. Default value of `%Y-%m-%d-${input}` creates names in the form of `YYYY-MM-DD-file_name`.
+:  a pattern used for filename generation. It is possible to use string templates
+and format strings for `os.date` function. The default pattern `%Y-%m-%d-${input}`
+creates names in the form of `YYYY-MM-DD-file_name`.
 
 header
 
-:  table with variables to be set in the YAML header in HTML files. If the table value is a function, it is executed with current parameters and HTML page DOM object as arguments.
+:  table with variables to be set in the YAML header in HTML files. If the
+table value is a function, it is executed with current parameters and HTML page
+DOM object as arguments.
 
 Example:
 
@@ -811,7 +997,7 @@ Example:
       }
     }
 
-### The `dvisvgm_hashes` extension
+## The `dvisvgm_hashes` extension
 
 options
 
@@ -819,108 +1005,182 @@ options
 
 cpu_cnt
 
-:  number of processor cores used for conversion. The extension tries to detect the available cores automatically by default.
+:  the number of processor cores used for the conversion. The extension tries to detect the available cores automatically by default.
 
 parallel_size
 
-:  number of pages used in each Dvisvgm call. The extension detects changed pages in the DVI file and construct multiple calls to Dvisvgm with only changed pages.
+:  the number of pages used in each Dvisvgm call. The extension detects changed
+pages in the DVI file and constructs multiple calls to Dvisvgm with only changed
+pages.
 
 scale
 
 :  SVG scaling.
 
-### The `odttemplate` filter and extension
+## The `odttemplate` filter and extension
 
 template
 
 :  filename of the template `ODT` file 
 
 
-`odttemplate` can also get the template filename from the `odttemplate` option from `tex4ht_sty_par` parameter. It can be set useing following command line call, for example:
+`odttemplate` can also get the template filename from the `odttemplate` option from `tex4ht_sty_par` parameter. It can be set using the following command line call:
 
      make4ht -f odt+odttemplate filename.tex "odttemplate=template.odt"
 
+## The `aeneas` filter
 
+skip\_elements
 
-# Configuration file {#configfile}
+:  List of CSS selectors that match elements that shouldn't be processed. Default value: `{ "math", "svg"}`.
 
-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.
+id\_prefix 
 
-## Location 
+:  prefix used in the ID attribute forming.
 
-The configuration file can be saved either in
-`$HOME/.config/make4ht/config.lua` or in `.make4ht` in the current directory or
-it's parents (up to `$HOME`).
+sentence\_match 
 
-## Additional commands
+:  Lua pattern used to match a sentence. Default value: `"([^%.^%?^!]*)([%.%?!]?)"`.
 
-There are two additional commands:
+## The  `make4ht-aeneas-config` package
 
-`Make:enable_extension(name)`
+Companion for the `aeneas` DOM filter is the `make4ht-aeneas-config` plugin. It
+can be used to write the Aeneas configuration file or execute Aeneas on the
+generated HTML files.
 
-:  require extension
+Available functions:
 
-`Make:disable_extension(name)`
+write\_job(parameters)
 
-:  disable extension
+:  write Aenas job configuration to `config.xml` file. See the [Aeneas
+   documentation](https://www.readbeyond.it/aeneas/docs/clitutorial.html#processing-jobs)
+   for more information about jobs.
 
-## Example
+execute(parameters)
 
-The following configuration add support for the `biber` command, requires
-`common_domfilters` extension and requires MathML
-output for math.
+:  execute Aeneas.
 
-    Make:add("biber", "biber ${input}")
-    Make:enable_extension "common_domfilters"
-    settings_add {
-      tex4ht_sty_par =",mathml"
+process\_files(parameters)
+
+:  process the audio and generated subtitle files.
+
+
+By default, a `SMIL` file is created. It is assumed that there is an audio file
+in the `mp3` format, named as the \TeX\ file. It is possible to use different formats
+and filenames using mapping.
+
+The configuration options can be passed directly to the functions or set using
+`filter_settings "aeneas-config" {parameters}` function.
+
+
+### Available parameters
+
+
+lang 
+
+:  document language. It is interfered from the HTML file, so it is not necessary to set it. 
+
+map 
+
+:  mapping between HTML, audio and subtitle files. More info below. 
+
+text\_type 
+
+:  type of input. The `aeneas` DOM filter produces an `unparsed` text type.
+
+id\_sort 
+
+:  sorting of id attributes. The default value is `numeric`.
+
+id\_regex 
+
+:  regular expression to parse the id attributes.
+
+sub\_format 
+
+:  generated subtitle format. The default value is `smil`.
+
+
+### Additional parameters for the job configuration file
+
+- description 
+- prefix 
+- config\_name 
+- keep\_config 
+
+
+
+It is possible to generate multiple HTML files from the \LaTeX\ source. For
+example, `tex4ebook` generates a separate file for each chapter or section. It is
+possible to set options for each HTML file, in particular names of the
+corresponding audio files. This mapping is done using the `map` parameter. 
+
+Example:
+
+    filter_settings "aeneas-config" {
+      map = {
+        ["sampleli1.html"] = {audio_file="sample.mp3"}, 
+        ["sample.html"] = false
+      }
     }
 
-# Command line options
+Table keys are the configured filenames. It is necessary to insert them as
+`["filename.html"]`, because of Lua syntax rules.
 
-    make4ht - build system for tex4ht
-    Usage:
-    make4ht [options] filename ["tex4ht.sty op." "tex4ht op." 
-         "t4ht op" "latex op"]
-    -b,--backend (default tex4ht) Backend used for xml generation.
-         possible values: tex4ht or lua4ht
-    -c,--config (default xhtml) Custom config file
-    -d,--output-dir (default "")  Output directory
-    -e,--build-file (default nil)  If build file name is different 
-         than `filename`.mk4
-    -f,--format  (default nil)  Output file format
-    -l,--lua  Use lualatex for document compilation
-    -m,--mode (default default) Switch which can be used in the makefile
-    -n,--no-tex4ht  Disable dvi file processing with tex4ht command
-    -s,--shell-escape Enables running external programs from LaTeX
-    -u,--utf8  For output documents in utf8 encoding
-    -v,--version  Print version number
-    -x,--xetex Use xelatex for document compilation
-    <filename> (string) Input file name
+This example maps audio file `sample.mp3` to a section subpage. The main HTML
+file, which may contain title and table of contents doesn't have a
+corresponding audio file.
+
+Filenames of the subfiles correspond to the chapter numbers, so they are not
+stable when a new chapter is added. It is possible to request filenames
+derived from the chapter titles using the `sec-filename` option for `tex4ht.sty`.
 
+### Available `map` options
 
-You can still invoke `make4ht` in the same way as `htlatex`:
 
-    make4ht filename "customcfg, charset=utf-8" "-cunihtf -utf8" "-dfoo"
+audio\_file 
 
-Note that this will not use `make4ht` routines for output directory making and
-copying. If you want to use them, change the line above to:
+:  the corresponding audio file 
 
-    make4ht -d foo filename "customcfg, charset=utf-8" "-cunihtf -utf8"
+sub\_file 
 
-This call has the same effect as the following:
+:  name of the generated subtitle file
+
+The following options are the same as their counterparts from the main parameters table and generally, don't need to be set:
+
+- prefix 
+- file\_desc 
+- file\_id 
+- text\_type 
+- id\_sort
+- id\_prefix 
+- sub\_format 
+
+
+### Full example
+
+
+    local domfilter = require "make4ht-domfilter"
+    local aeneas_config = require "make4ht-aeneas-config"
+    
+    filter_settings "aeneas-config" {
+      map = {
+        ["krecekli1.xhtml"] = {audio_file="krecek.mp3"}, 
+        ["krecek.xhtml"] = false
+      }
+    }
+    
+    local process = domfilter {"aeneas"}
+    Make:match("html$", process)
+
+    if mode == "draft" then
+      aeneas_config.process_files {}
+    else
+      aeneas_config.execute {}
+    end
 
-    make4ht -u -c customcfg -d foo filename
 
-Output directory doesn't have to exist, it will be created automatically. 
-Specified path can be relative to current directory, or absolute:
 
-    make4ht -d use/current/dir/ filename
-    make4ht -d ../gotoparrentdir filename
-    make4ht -d ~/gotohomedir filename
-    make4ht -d c:\documents\windowspathsareworkingtoo filename
 
 # Troubleshooting 
 
@@ -932,24 +1192,26 @@ Sometimes, you may get a similar error:
 
 It may be caused by a following `make4ht` invocation:
 
-    make4ht hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8" -d foo
+    $ make4ht hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8" -d foo
 
 The command line option parser is confused by mixing options for `make4ht` and
-`tex4ht` in this case and tries to interpret the `-cunihtf -utf8`, which are
-options for `tex4ht` command as `make4ht` options. To fix that, you can either
-move the `-d foo` directly after `make4ht` command:
+\TeX4ht\ in this case. It tries to interpret the `-cunihtf -utf8`, which are
+options for the `tex4ht` command, as `make4ht` options. To fix that, try to
+move the `-d foo` directly after the `make4ht` command:
 
-    make4ht -d foo hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8"
+    $ make4ht -d foo hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8"
 
-Another option is to add a space before `tex4ht` options:
+Another option is to add a space before the `tex4ht` options:
 
-    make4ht hello.tex "customcfg,charset=utf-8" " -cunihtf -utf8" -d foo
+    $ make4ht hello.tex "customcfg,charset=utf-8" " -cunihtf -utf8" -d foo
 
 The former way is preferable, though.
 
 ## Filenames containing spaces
 
-`tex4ht` cannot handle filenames containing spaces. `make4ht` thus replaces spaces in input file names with underscores, so generated XML files use underscores instead of spaces as well.
+`tex4ht` command cannot handle filenames containing spaces. to fix this issue, `make4ht` 
+replaces spaces in the input filenames with underscores. The generated
+XML filenames use underscores instead of spaces as well.
 
 ## Filenames containing non-ASCII characters
 
diff --git a/Master/texmf-dist/doc/support/make4ht/changelog.tex b/Master/texmf-dist/doc/support/make4ht/changelog.tex
index 8d46424decf..f2b0fd77353 100644
--- a/Master/texmf-dist/doc/support/make4ht/changelog.tex
+++ b/Master/texmf-dist/doc/support/make4ht/changelog.tex
@@ -3,6 +3,262 @@
 
 \begin{itemize}
 \item
+  2019/11/01
+
+  \begin{itemize}
+  \tightlist
+  \item
+    version 0.3 released
+  \item
+    added \texttt{Make:makeindex}, \texttt{Make:xindex} and
+    \texttt{Make:bibtex} commands.
+  \end{itemize}
+\item
+  2019/10/25
+
+  \begin{itemize}
+  \tightlist
+  \item
+    modified the \texttt{Make:xindy} command to use the indexing
+    mechanism.
+  \end{itemize}
+\item
+  2019/10/24
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added functions for preparing and cleaning of the index files in
+    \texttt{make4ht-indexing.lua}.
+  \end{itemize}
+\item
+  2019/10/23
+
+  \begin{itemize}
+  \tightlist
+  \item
+    replaced \texttt{os.execute} function with \texttt{mkutils.execute}.
+    It uses the logging mechanism for the output.
+  \item
+    finished transforming of filters, extensions and formats to the
+    logging system.
+  \end{itemize}
+\item
+  2019/10/22
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added \texttt{tablerows} domfilter.
+  \item
+    added the \texttt{tablerows} domfilter to the
+    \texttt{common\_domfilters} extension.
+  \item
+    converted most of the filters to use the logging mechanism.
+  \end{itemize}
+\item
+  2019/10/20
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added \texttt{status} log level.
+  \end{itemize}
+\item
+  2019/10/18
+
+  \begin{itemize}
+  \tightlist
+  \item
+    converted most print commands to use the logging mechanism.
+  \item
+    added \texttt{output} log level used for printing of the commands
+    output.
+  \end{itemize}
+\item
+  2019/10/17
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added \texttt{-\/-loglevel} CLI parameter.
+  \item
+    added logging mechanism.
+  \item
+    moved \texttt{htlatex} related code to \texttt{make4ht-htlatex.lua}
+    from \texttt{mkutils.lua}
+  \end{itemize}
+\item
+  2019/10/11
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added \texttt{xindy} settings.
+  \item
+    added simple regular expression to detect errors in the log file,
+    because log parsing can be slow.
+  \end{itemize}
+\item
+  2019/10/09
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added the \texttt{interaction} parameter for the \texttt{htlatex}
+    command. The default value is \texttt{batchmode} to suppress the
+    user input on errors, and to suppress full log output to the
+    terminal.
+  \item
+    added the \texttt{make4ht-errorlogparser} module. It is used to
+    parse errors in the \texttt{htlatex} run unless \texttt{interaction}
+    is set to \texttt{errorstopmode}.
+  \end{itemize}
+\item
+  2019/10/08
+
+  \begin{itemize}
+  \tightlist
+  \item
+    set up Github Actions pipeline to compile the documentation to HTML
+    and publish it at https://www.kodymirus.cz/make4ht/make4ht-doc.html.
+  \end{itemize}
+\item
+  2019/10/07
+
+  \begin{itemize}
+  \tightlist
+  \item
+    don't move the \texttt{common\_domfilters} extension to the first
+    place in the file matches pipeline. We may want to run \texttt{tidy}
+    or regex filters first, to fix XML validation errors.
+  \end{itemize}
+\item
+  2019/10/04
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added HTML documentation.
+  \end{itemize}
+\item
+  2019/09/27
+
+  \begin{itemize}
+  \tightlist
+  \item
+    don't convert Latin 1 entities to Unicode in the
+    \texttt{entities\_to\_unicode} extension.
+  \end{itemize}
+\item
+  2019/09/20
+
+  \begin{itemize}
+  \tightlist
+  \item
+    fixed bugs in the temporary directory handling for the ODT output.
+  \end{itemize}
+\item
+  2019/09/13
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added \texttt{preprocess\_input} extension. It enables compilation
+    of formats supported by \href{https://yihui.name/knitr/}{Knitr}
+    (\texttt{.Rnw}, \texttt{.Rtex}, \texttt{.Rmd}, \texttt{.Rrst}) and
+    also Markdown and reStructuredText formats.
+  \end{itemize}
+\item
+  2019/09/12
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added support for the ODT files in \texttt{common\_domfilters}
+    extension.
+  \item
+    renamed \texttt{charclases} option for the \texttt{joincharacters}
+    DOM filter to \texttt{charclasses}.
+  \item
+    don't execute the \texttt{fixentities} filter before Xtpipes, it
+    makes no sense.
+  \end{itemize}
+\item
+  2019/09/11
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added support for Biber in the build files.
+  \end{itemize}
+\item
+  2019/08/28
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added support for input from \texttt{stdin}.
+  \end{itemize}
+\item
+  2019/08/27
+
+  \begin{itemize}
+  \tightlist
+  \item
+    fixed \texttt{-jobname} detection regex.
+  \item
+    added function \texttt{handle\_jobname}.
+  \item
+    added the \texttt{-\/-jobname} command line option.
+  \end{itemize}
+\item
+  2019/08/26
+
+  \begin{itemize}
+  \tightlist
+  \item
+    quote file names and paths in \texttt{xtpipes} and \texttt{tidy}
+    invocation.
+  \end{itemize}
+\item
+  2019/08/25
+
+  \begin{itemize}
+  \tightlist
+  \item
+    the issue tracker link in the help message is now configurable.
+  \item
+    fixed bug in the XeTeX handling: the \texttt{.xdv} argument for
+    \texttt{tex4ht} wasn't used if command line arguments for
+    \texttt{tex4ht} were present.
+  \end{itemize}
+\item
+  2019/07/03
+
+  \begin{itemize}
+  \tightlist
+  \item
+    new DOM filter: \texttt{odtpartable}. It fixes tables nested in
+    paragraphs in the ODT format.
+  \end{itemize}
+\item
+  2019/06/13
+
+  \begin{itemize}
+  \tightlist
+  \item
+    new DOM extension: \texttt{collapsetoc}.
+  \end{itemize}
+\item
+  2019/05/29
+
+  \begin{itemize}
+  \tightlist
+  \item
+    new module: \texttt{make4ht-indexing} for working with index files.
+  \end{itemize}
+\item
   2019/05/24
 
   \begin{itemize}
@@ -18,7 +274,7 @@
   \begin{itemize}
   \tightlist
   \item
-    fixed infinite loop bug in the \texttt{dvisvgm\_hashes} extension
+    fixed infinite loop bug in the \texttt{dvisvgm\_hashes} extension.
   \end{itemize}
 \item
   2019/04/09
diff --git a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf
index 0b7dd091ea1..506be1df428 100644
--- a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf
+++ b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf
diff --git a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex
index 6815e50606f..24f94aa1315 100644
--- a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex
+++ b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex
@@ -3,19 +3,24 @@
 
 \usepackage[english]{babel}
 \usepackage{hyperref}
+\newcommand\authormail[1]{\footnote{\textless\url{#1}\textgreater}}
 \ifdefined\HCode
-\usepackage[T1]{fontenc}
-\usepackage[utf8]{inputenc}
-\else
+\renewcommand\authormail[1]{\space\textless\Link[#1]{}{}#1\EndLink\textgreater}
+\fi
+
 \usepackage{fontspec}
 \setmainfont{TeX Gyre Schola}
-\setmonofont[Scale=MatchLowercase]{Inconsolatazi4}
-\fi
+% \setmonofont[Scale=MatchLowercase]{Inconsolatazi4}
+\IfFontExistsTF{Noto Sans Mono Regular}{%
+  \setmonofont[Scale=MatchLowercase]{Noto Sans Mono Regular}
+}{\setmonofont{NotoMono-Regular.ttf}}
+\usepackage{upquote}
+
 \usepackage{microtype}
 \providecommand\tightlist{\relax}
 
 \title{The \texttt{make4ht} build system}
-\author{Michal Hoftich\footnote{\url{michal.h21@gmail.com}}}
+\author{Michal Hoftich\authormail{michal.h21@gmail.com}}
 \date{Version \version\\\gitdate}
 \begin{document}
 \maketitle
diff --git a/Master/texmf-dist/doc/support/make4ht/readme.tex b/Master/texmf-dist/doc/support/make4ht/readme.tex
index c9fc0a2f3ed..ff1d942d18d 100644
--- a/Master/texmf-dist/doc/support/make4ht/readme.tex
+++ b/Master/texmf-dist/doc/support/make4ht/readme.tex
@@ -1,125 +1,267 @@
 \hypertarget{introduction}{%
 \section{Introduction}\label{introduction}}
 
-\texttt{make4ht} is a simple build system for \texttt{tex4ht}, \TeX~to
-XML converter. It provides a command line tool that drive the conversion
-process. It also provides a library which can be used to create
-customized conversion tools. An example of such conversion tool is
-\href{https://github.com/michal-h21/tex4ebook}{tex4ebook} for conversion
-of \TeX~to ePub and other e-book formats.
-
-\hypertarget{how-it-works}{%
-\subsection{How it works}\label{how-it-works}}
-
-\hypertarget{the-issues-with-default-tex4ht-conversion-commands}{%
-\subsubsection{\texorpdfstring{The issues with default \texttt{tex4ht}
-conversion
-commands}{The issues with default tex4ht conversion commands}}\label{the-issues-with-default-tex4ht-conversion-commands}}
-
-\texttt{tex4ht} system supports several output formats, most notably
-\texttt{XHTML}, \texttt{HTML\ 5} and \texttt{ODT}. The conversion can be
-invoked using several commands. These commands invoke LaTeX~or Plain TeX
-with special instructions to load \texttt{tex4ht.sty} package. The
-\TeX~run produces special \texttt{DVI} file which contains the code for
-desired output format. Produced \texttt{DVI} file is then processed and
-desired output files are created.
-
-The basic command provided by \texttt{tex4ht} is named \texttt{htlatex}.
-It compiles \LaTeX~ files to \texttt{HTML} with this command sequence:
+\texttt{make4ht} is a build system for \TeX4ht, \TeX~to XML converter.
+It provides a command line tool that drives the conversion process. It
+also provides a library that can be used to create customized conversion
+tools. An example of such a tool is
+\href{https://github.com/michal-h21/tex4ebook}{tex4ebook}, a tool for
+conversion from \TeX~to ePub and other e-book formats.
+
+The basic conversion from \LaTeX~to \texttt{HTML} using \texttt{make4ht}
+can be executed using the following command:
+
+\begin{verbatim}
+$ make4ht filename.tex
+\end{verbatim}
+
+It will produce a file named \texttt{filename.html} if the compilation
+goes without fatal errors.
+
+\hypertarget{clioptions}{%
+\section{Command line options}\label{clioptions}}
+
+\label{sec:clioptions}
+
+\begin{verbatim}
+make4ht - build system for TeX4ht
+Usage:
+make4ht [options] filename ["tex4ht.sty op." "tex4ht op." 
+     "t4ht op" "latex op"]
+-a,--loglevel (default status) Set log level.
+            possible values: debug, info, status, warning, error, fatal
+-b,--backend (default tex4ht) Backend used for xml generation.
+     possible values: tex4ht or lua4ht
+-c,--config (default xhtml) Custom config file
+-d,--output-dir (default "")  Output directory
+-e,--build-file (default nil)  If build filename is different 
+     than `filename`.mk4
+-f,--format  (default nil)  Output file format
+-j,--jobname (default nil)  Set the jobname
+-l,--lua  Use lualatex for document compilation
+-m,--mode (default default) Switch which can be used in the makefile
+-n,--no-tex4ht  Disable DVI file processing with tex4ht command
+-s,--shell-escape Enables running external programs from LaTeX
+-u,--utf8  For output documents in utf8 encoding
+-x,--xetex Use xelatex for document compilation
+-v,--version  Print version number
+<filename> (string) Input filename
+\end{verbatim}
+
+It is still possible to invoke \texttt{make4ht} in the same way as is
+invoked \texttt{htlatex}:
+
+\begin{verbatim}
+$ make4ht filename "customcfg, charset=utf-8" "-cunihtf -utf8" "-dfoo"
+\end{verbatim}
+
+Note that this will not use \texttt{make4ht} routines for the output
+directory handling. See section \ref{sec:output-dir} for more
+information about this issue. To use these routines, change the previous
+listing to:
+
+\begin{verbatim}
+$ make4ht -d foo filename "customcfg, charset=utf-8" "-cunihtf -utf8"
+\end{verbatim}
+
+This call has the same effect as the following:
+
+\begin{verbatim}
+$ make4ht -u -c customcfg -d foo filename
+\end{verbatim}
+
+Output directory doesn't have to exist, it will be created
+automatically. Specified path can be relative to the current directory,
+or absolute:
+
+\begin{verbatim}
+$ make4ht -d use/current/dir/ filename
+$ make4ht -d ../gotoparrentdir filename
+$ make4ht -d ~/gotohomedir filename
+$ make4ht -d c:\documents\windowspathsareworkingtoo filename
+\end{verbatim}
+
+The short options that don't take parameters can be collapsed:
+
+\begin{verbatim}
+$ make4ht -ulc customcfg -d foo filename
+\end{verbatim}
+
+To pass output from the other commands to \texttt{make4ht} use the
+\texttt{-} character as a filename. It is best to use this feature
+together with the \texttt{-\/-jobname} or \texttt{-j} option.
+
+\begin{verbatim}
+$ cat hello.tex | make4ht -j world -
+\end{verbatim}
+
+By default, \texttt{make4ht} tries to be quiet, so it hides most of the
+command line messages and the output from the executed commands. It will
+display only status messages, warnings and errors. The logging level can
+be selected using the \texttt{-\/-loglevel} or \texttt{-a} options. If
+the compilation fails, it may be useful to display more information
+using the \texttt{info} or \texttt{debug} levels.
 
 \begin{verbatim}
-latex $latex_options 'code for loading tex4ht.sty \input{filename}'
-latex $latex_options 'code for loading tex4ht.sty \input{filename}'
-latex $latex_options 'code for loading tex4ht.sty \input{filename}'
-tex4ht $tex4ht_options filename
-t4ht $t4ht_options filename
+$ make4ht -a debug faulty.tex
+\end{verbatim}
+
+\hypertarget{why-make4ht-htlatex-issues}{%
+\section{\texorpdfstring{Why \texttt{make4ht}? -- \texttt{htlatex}
+issues}{Why make4ht? -- htlatex issues}}\label{why-make4ht-htlatex-issues}}
+
+\TeX4ht~system supports several output formats, most notably
+\texttt{XHTML}, \texttt{HTML\ 5} and \texttt{ODT}, but it also supports
+\texttt{TEI} or \texttt{Docbook}.
+
+The conversion can be invoked using several scripts, which are
+distributed with \TeX4ht. They differ in parameters passed to the
+underlying commands.
+
+These scripts invoke \LaTeX~or Plain \TeX~with special instructions to
+load the \texttt{tex4ht.sty} package. The \TeX~run produces a special
+\texttt{DVI} file that contains the code for the desired output format.
+The produced \texttt{DVI} file is then processed using the
+\texttt{tex4ht} command, which in conjunction with the \texttt{t4ht}
+command produces the desired output files.
+
+\hypertarget{passing-command-line-arguments}{%
+\subsection{Passing command line
+arguments}\label{passing-command-line-arguments}}
+
+The basic conversion script provided by \TeX4ht~system is named
+\texttt{htlatex}. It compiles \LaTeX~ files to \texttt{HTML} with this
+command sequence:
+
+\begin{verbatim}
+$ latex $latex_options 'code for loading tex4ht.sty \input{filename}'
+$ latex $latex_options 'code for loading tex4ht.sty \input{filename}'
+$ latex $latex_options 'code for loading tex4ht.sty \input{filename}'
+$ tex4ht $tex4ht_options filename
+$ t4ht $t4ht_options filename
 \end{verbatim}
 
 The options for various parts of the system can be passed on the command
 line:
 
 \begin{verbatim}
-htlatex filename "tex4ht.sty options" "tex4ht_options" "t4ht_options" "latex_options"
+$ htlatex filename "tex4ht.sty options" "tex4ht_options" "t4ht_options" "latex_options"
 \end{verbatim}
 
 For basic \texttt{HTML} conversion it is possible to use the most basic
 invocation:
 
 \begin{verbatim}
-htlatex filename.tex
+$ htlatex filename.tex
 \end{verbatim}
 
-It can be much more involved for \texttt{HTML\ 5} output in
+It can be much more involved for the \texttt{HTML\ 5} output in
 \texttt{UTF-8} encoding:
 
 \begin{verbatim}
-htlatex filename.tex "xhtml,html5,charset=utf-8" "-cmozhtf -utf8"
+$ htlatex filename.tex "xhtml,html5,charset=utf-8" " -cmozhtf -utf8"
 \end{verbatim}
 
 \texttt{make4ht} can simplify it:
 
 \begin{verbatim}
-make4ht -uf html5 filename.tex
+$ make4ht -u filename.tex
 \end{verbatim}
 
-Another issue is the fixed compilation order and hard-coded number of
-LaTeX invocations.
+The \texttt{-u} option requires the \texttt{UTF-8} encoding.
+\texttt{HTML\ 5} is used as the default output format by
+\texttt{make4ht}.
+
+More information about the command line arguments can be found in
+section \ref{sec:clioptions}.
+
+\hypertarget{compilation-sequence}{%
+\subsection{Compilation sequence}\label{compilation-sequence}}
+
+\texttt{htlatex} has a fixed compilation order and a hard-coded number
+of \LaTeX~invocations.
 
-When you need to run a program which interact with LaTeX, such as
-\texttt{Makeindex} or \texttt{Bibtex}, you need to create a new script
-based on \texttt{htlatex}, or run \texttt{htlatex} twice, which means
-that LaTeX will be invoked six times. This can lead to significantly
-long compilation times. \texttt{make4ht} provides build files and
-extensions, which can be used for interaction with external tools.
+It is not possible to execute additional commands during the
+compilation. When we want to run a program that interacts with \LaTeX,
+such as \texttt{Makeindex} or \texttt{Bibtex}, we have two options. The
+first option is to create a new script based on \texttt{htlatex} and add
+the wanted commands to the modified script. The second option is to
+execute \texttt{htlatex}, then the additional and then \texttt{htlatex}
+again. The second option means that \LaTeX~will be invoked six times, as
+each call to \texttt{htlatex} executes three calls to \LaTeX. This can
+lead to significantly long compilation times.
 
-It is also possible to have several compilation modes. When you just add
-new text to a document, which doesn't contain cross-references, don't
-add new stuff to the table of contents, etc., it is possible to use the
-\texttt{draft} mode which will invoke LaTeX only once. It can save quite
-a lot of the compilation time:
+\texttt{make4ht} provides a solution for this issue using a build file,
+or extensions. These can be used for interaction with external tools.
+
+\texttt{make4ht} also provides compilation modes, which enables to
+select commands that should be executed using a command line option.
+
+There is a built-in \texttt{draft} mode, which invokes \LaTeX~only once,
+instead of the default three invocations. It is useful for the
+compilations of the document before its final stage, when it is not
+important that all cross-references work. It can save quite a lot of the
+compilation time:
 
 \begin{verbatim}
-make4ht -um draft -f html5 filename.tex
+$ make4ht -um draft filename.tex
 \end{verbatim}
 
-There are also issues with a behaviour of the \texttt{t4ht} application.
-It reads file \texttt{filename.lg}, generated by \texttt{tex4ht}, where
-are instructions about generated files, \texttt{CSS} instructions, calls
-to external applications, instructions for image conversions etc. It can
-be instructed to copy generated files to some output directory, but it
-doesn't preserve directory structure, so when you have images in a
-subdirectory, they will be copied to the output directory. Links will be
-pointing to a non-existing subdirectory. The following command should
-copy all output files to the correct destinations.
+More information about the build files can be found in section
+\ref{sec:buildfiles}.
+
+\hypertarget{handling-of-the-generated-files}{%
+\subsection{Handling of the generated
+files}\label{handling-of-the-generated-files}}
+
+\label{sec:output-dir}
+
+There are also issues with the behavior of the \texttt{t4ht}
+application. It reads the \texttt{.lg} file generated by the
+\texttt{tex4ht} command. This file contains information about the
+generated files, \texttt{CSS} instructions, calls to the external
+applications, instructions for image conversions, etc.
+
+\texttt{t4ht} can be instructed to copy the generated files to an output
+directory, but it doesn't preserve the directory structure. When the
+images are placed in a\\
+subdirectory, they will be copied to the output directory, losing the
+directory structure. Links will be pointing to a non-existing
+subdirectory. The following command should copy all output files to the
+correct destinations.
 
 \begin{verbatim}
-make4ht -d outputdir filename.tex
+$ make4ht -d outputdir filename.tex
 \end{verbatim}
 
-The image conversion is configured in the
-\href{http://www.tug.org/applications/tex4ht/mn35.html\#index35-73001}{env
-file}, which has really strange syntax based and the rules are
-\href{http://www.tug.org/applications/tex4ht/mn-unix.html\#index27-69005}{os
-dependent}. \texttt{make4ht} provides simpler means for the image
-conversion in the build files.
+\hypertarget{image-conversion-and-post-processing-of-the-generated-files}{%
+\subsection{Image conversion and post-processing of the generated
+files}\label{image-conversion-and-post-processing-of-the-generated-files}}
+
+\TeX4ht~can convert parts of the document to images. This is useful for
+diagrams or complicated math, for example.
 
-With \texttt{make4ht} build files, we have simple mean to fix these
-issues. We can change image conversion parameters without the need to
-modify the \texttt{env\ file}, or execute actions on the output files.
-These actions can be either external programs such as \texttt{xslt}
-processors or \texttt{HTML\ tidy} or \texttt{Lua} functions.
+By default, the image conversion is configured in a
+\href{http://www.tug.org/applications/tex4ht/mn35.html\#index35-73001}{\texttt{.env}
+file}. It has a bit of strange syntax, with
+\href{http://www.tug.org/applications/tex4ht/mn-unix.html\#index27-69005}{operating
+system dependent} rules. \texttt{make4ht} provides simpler means for the
+image conversion in the build files. It is possible to change the image
+conversion parameters without a need to modify the \texttt{.env} file.
+The process is described in section \ref{sec:imageconversion}.
 
-The idea is to make system controlled by a build file. Because
-\texttt{Lua} interpreter is included in modern TeX distributions and
-\texttt{Lua} is ideal language for such task, it was chosen as language
-in which the build scripts are written.
+It is also possible to post-process the generated output files. The
+post-processing can be done either using external programs such as
+\texttt{XSLT} processors and \texttt{HTML\ Tidy} or using \texttt{Lua}
+functions. More information can be found in section
+\ref{sec:postprocessing}.
 
 \hypertarget{output-file-formats-and-extensions}{%
 \section{Output file formats and
 extensions}\label{output-file-formats-and-extensions}}
 
-The default output format used by \texttt{make4ht} is \texttt{html5}.
-Different format can be requested using the \texttt{-\/-format} option.
+The default output format used by \texttt{make4ht} is \texttt{html5}. A
+different format can be requested using the \texttt{-\/-format} option.
 Supported formats are:
 
 \begin{itemize}
@@ -149,50 +291,63 @@ The extensions can be enabled or disabled by appending
 \texttt{+EXTENSION} or \texttt{-EXTENSION} after the output format name:
 
 \begin{verbatim}
- make4ht -uf html5+tidy filename.tex
+ $ make4ht -uf html5+tidy filename.tex
 \end{verbatim}
 
 Available extensions:
 
 \begin{description}
-\item[latexmk\_build]
-use \texttt{Latexmk} for \LaTeX~compilation.
-\item[tidy]
-clean the \texttt{HTML} files using the \texttt{tidy} command.
-\item[dvisvgm\_hashes]
-efficient generation of SVG pictures using Dvisvgm. It can utilize
-multiple processor cores and generates only changed images.
 \item[common\_filters]
 clean the output HTML files using filters.
 \item[common\_domfilters]
 clean the HTML file using DOM filters. It is more powerful than
 \texttt{common\_filters}. Used DOM filters are \texttt{fixinlines},
-\texttt{idcolons} and \texttt{joincharacters}.
+\texttt{idcolons}, \texttt{joincharacters}, and \texttt{tablerows}.
+\item[dvisvgm\_hashes]
+efficient generation of SVG pictures using Dvisvgm. It can utilize
+multiple processor cores and generates only changed images.
 \item[join\_colors]
 load the \texttt{joincolors} domfilter for all HTML files.
+\item[latexmk\_build]
+use \href{https://ctan.org/pkg/latexmk?lang=en}{Latexmk} for the
+\LaTeX~compilation.
 \item[mathjaxnode]
 use \href{https://github.com/pkra/mathjax-node-page/}{mathjax-node-page}
 to convert from MathML code to HTML + CSS or SVG. See
 \protect\hyperlink{mathjaxsettings}{the available settings}.
 \item[odttemplate]
-automatically load the \texttt{odttemplate} filter.
+it automatically loads the \texttt{odttemplate} filter (page
+\pageref{sec:odttemplate}).
+\item[preprocess\_input]
+compilation of the formats supported by
+\href{https://yihui.name/knitr/}{Knitr} (\texttt{.Rnw}, \texttt{.Rtex},
+\texttt{.Rmd}, \texttt{.Rrst}) and also Markdown and reStructuredText
+formats. It requires \href{https://www.r-project.org/}{R} +
+\href{https://yihui.name/knitr/}{Knitr} installation, it requires also
+\href{https://pandoc.org/}{Pandoc} for formats based on Markdown or
+reStructuredText.
 \item[staticsite]
-build the document in form suitable for static site generators like
+build the document in a form suitable for static site generators like
 \href{https://jekyllrb.com/}{Jekyll}.
+\item[tidy]
+clean the \texttt{HTML} files using the \texttt{tidy} command.
 \end{description}
 
 \hypertarget{build-files}{%
 \section{Build files}\label{build-files}}
 
+\label{sec:buildfiles}
+
 \texttt{make4ht} supports build files. These are \texttt{Lua} scripts
-which can adjust the build process. You can request external
-applications like \texttt{bibtex} or \texttt{makeindex}, pass options to
+that can adjust the build process. They can request external
+applications like \texttt{BibTeX} or \texttt{Makeindex}, pass options to
 the commands, modify the image conversion process, or post-process the
 generated files.
 
 \texttt{make4ht} tries to load default build file named as
-\texttt{filename\ +\ .mk4\ extension}. You can choose different build
-file with \texttt{-e} or \texttt{-\/-build-file} command line option.
+\texttt{filename\ +\ .mk4\ extension}. It is possible to select a
+different build file with \texttt{-e} or \texttt{-\/-build-file} command
+line option.
 
 Sample build file:
 
@@ -201,184 +356,228 @@ Make:htlatex()
 Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}")
 \end{verbatim}
 
-\texttt{Make:htlatex()} is preconfigured command for calling LaTeX with
-\texttt{tex4ht} loaded on the input file. In this case, it will be
-called one time. After compilation, the \texttt{tidy} command is
-executed on the output \texttt{HTML} file.
+\texttt{Make:htlatex()} is preconfigured command for calling \LaTeX~with
+the \texttt{tex4ht.sty} package loaded. In this example, it will be
+executed only once. After the compilation, the \texttt{tidy} command is
+executed on the output \texttt{HTML} files.
 
-Note that you don't have to call \texttt{tex4ht} and \texttt{t4ht}
+Note that it is not necessary to call \texttt{tex4ht} and \texttt{t4ht}
 commands explicitly in the build file, they are called automatically.
 
 \hypertarget{user-commands}{%
 \subsection{User commands}\label{user-commands}}
 
-You can add more commands like \texttt{Make:htlatex} using
+It is possible to add more commands like \texttt{Make:htlatex} using the
 \texttt{Make:add} command:
 
 \begin{verbatim}
-Make:add("name", "command", {parameters}, repetition)
+Make:add("name", "command", {settings table}, repetition)
 \end{verbatim}
 
-The \texttt{name} and \texttt{command} parameters are required, rest of
-the parameters are optional.
+This defines the \texttt{name} command, which can be then executed using
+\texttt{Make:name()} command in the build file.
 
-This defines \texttt{name} command, which can be then executed as
-\texttt{Make:name()} command.
+The \texttt{name} and \texttt{command} parameters are required, the rest
+of the parameters are optional.
 
-\hypertarget{provided-commands}{%
-\subsubsection{Provided commands}\label{provided-commands}}
+The defined command receives a table with settings as a parameter at the
+call time. The default settings are provided by \texttt{make4ht}.
+Additional settings can be declared in the \texttt{Make:add} commands,
+user can also override the default settings when the command is executed
+in the build file:
 
-\begin{description}
-\item[\texttt{Make:htlatex}]
-One call to TeX engine with special configuration for \texttt{tex4ht}
-loading.
-\item[\texttt{Make:latexmk}]
-Use \texttt{Latexmk} for the document compilation. \texttt{tex4ht} will
-be loaded automatically.
-\item[\texttt{Make:tex4ht}]
-Process the \texttt{DVI} file and creates the output files.
-\item[\texttt{Make:t4ht}]
-Creates the CSS file.
-\end{description}
+\begin{verbatim}
+Make:name({hello="world"})
+\end{verbatim}
+
+More information about settings, including the default settings provided
+by \texttt{make4ht}, can be found in section \ref{sec:settings} on page
+\pageref{sec:settings}.
 
-\hypertarget{command-function}{%
-\subsubsection{Command function}\label{command-function}}
+\hypertarget{the-command-function}{%
+\subsubsection{\texorpdfstring{The \texttt{command}
+function}{The command function}}\label{the-command-function}}
 
-The \texttt{command} parameter can be either string template or
+\label{sec:commandfunction}
+
+The \texttt{command} parameter can be either a string template or
 function:
 
 \begin{verbatim}
 Make:add("text", "echo hello, input file: ${input}")
-Make:add("function", function(params) 
-  for k, v in pairs(params) do 
-    print(k..": "..v) 
-  end, {custom="Hello world"}
-)
 \end{verbatim}
 
-The template can get variable value from the parameters table using a
-\texttt{\$\{var\_name\}} placeholder. Templates are executed using
-operating system, so they should invoke existing OS commands. Function
-commands may execute system commands using \texttt{os.execute} function.
-
-\hypertarget{parameters-table}{%
-\subsubsection{Parameters table}\label{parameters-table}}
+The template can get a variable value from the parameters table using a
+\texttt{\$\{var\_name\}} placeholder. Templates are executed using the
+operating system, so they should invoke existing OS commands.
 
-\texttt{parameters} parameter is optional, it can be table or
-\texttt{nil} value, which should be used if you want to use the
-\texttt{repetition} parameter, but don't want to modify the parameters
-table.
+\hypertarget{the-settings-table-table}{%
+\subsubsection{\texorpdfstring{The \texttt{settings\ table}
+table}{The settings table table}}\label{the-settings-table-table}}
 
-The table with default parameters is passed to all commands, they can be
-accessed from command functions or templates. When you specify your own
-parameters in the command definition, these additional parameters are
-added to the default parameters table for this particular command. You
-can override the default parameters in the parameters table.
+The \texttt{settings\ table} parameter is optional. If it is present, it
+should be a table with new settings available in the command. It can
+also override the default \texttt{make4ht} settings for the defined
+command.
 
-The default parameters are following:
-
-\begin{description}
-\item[\texttt{htlatex}]
-used compiler
-\item[\texttt{input}]
-it is output file name in fact
-\item[\texttt{tex\_file}]
-input TeX file
-\item[\texttt{latex\_par}]
-parameters to \texttt{latex}
-\item[\texttt{packages}]
-insert additional LaTeX code which is inserted before
-\texttt{\textbackslash{}documentclass}. Useful for passing options to
-packages or additional packages loading
-\item[\texttt{tex4ht\_sty\_par}]
-parameters to \texttt{tex4ht.sty}
-\item[\texttt{tex4ht\_par}]
-parameters to the \texttt{tex4ht} application
-\item[\texttt{t4ht\_par}]
-parameters to the \texttt{t4ht} application
-\item[\texttt{outdir}]
-the output directory
-\item[\texttt{repetition}]
-limit number of command execution.
-\item[\texttt{correct\_exit}]
-expected \texttt{exit\ code} from the command. The compilation will be
-terminated if the command \texttt{exit\ code} is different.
-\end{description}
+\begin{verbatim}
+Make:add("sample_function", function(params) 
+  for k, v in pairs(params) do 
+    print(k..": "..v) 
+  end, {custom="Hello world"}
+)
+\end{verbatim}
 
 \hypertarget{repetition}{%
 \subsubsection{Repetition}\label{repetition}}
 
-Repetition is number which specifies a maximal number of executions of
-the particular command. This is used for instance for \texttt{tex4ht}
-and \texttt{t4ht} commands, as they should be executed only once in the
-compilation. They would be executed multiple times if you include them
-in the build file because they are called by \texttt{make4ht} by
-default. Because these commands allow only one \texttt{repetition}, the
-second execution will be blocked.
+The \texttt{repetition} parameter specifies the maximum number of
+executions of the particular command. This is used for instance for
+\texttt{tex4ht} and \texttt{t4ht} commands, as they should be executed
+only once in the compilation. They would be executed multiple times when
+they are included in the build file, as they are called by
+\texttt{make4ht} by default. Because these commands allow only one
+\texttt{repetition}, the second execution is blocked.
 
 \hypertarget{expected-exit-code}{%
 \subsubsection{Expected exit code}\label{expected-exit-code}}
 
 You can set the expected exit code from a command with a
-\texttt{correct\_exit} key in the parameters table. The compilation will
-be stopped when the command returns a different exit code.
-
-This mechanism isn't used for LaTeX (for all TeX engines and formats, in
-fact), because it doesn't differentiate between fatal and non-fatal
-errors, and it returns the same exit code in all cases. Log parsing is
-used because of that, error code \texttt{1} is returned in the case of
-fatal error, \texttt{0} is used otherwise. The \texttt{Make.testlogfile}
+\texttt{correct\_exit} key in the settings table. The compilation will
+be terminated when the command returns a different exit code.
+
+\begin{verbatim}
+Make:add("biber", "biber ${input}", {correct_exit=0})
+\end{verbatim}
+
+Commands that execute lua functions can return the numerical values
+using the \texttt{return} statement.
+
+This mechanism isn't used for \TeX, because it doesn't differentiate
+between fatal and non-fatal errors. It returns the same exit code in all
+cases. Because of this, log parsing is used for a fatal error detection
+instead. Error code value \texttt{1} is returned in the case of a fatal
+error, \texttt{0} is used otherwise. The \texttt{Make.testlogfile}
 function can be used in the build file to detect compilation errors in
 the TeX log file.
 
+\hypertarget{provided-commands}{%
+\subsection{Provided commands}\label{provided-commands}}
+
+\begin{description}
+\item[\texttt{Make:htlatex}]
+One call to the TeX engine with special configuration for loading of the
+\texttt{tex4ht.sty} package.
+\item[\texttt{Make:latexmk}]
+Use \texttt{Latexmk} for the document compilation. \texttt{tex4ht.sty}
+will be loaded automatically.
+\item[\texttt{Make:tex4ht}]
+Process the \texttt{DVI} file and create output files.
+\item[\texttt{Make:t4ht}]
+Create the CSS file and generate images.
+\item[\texttt{Make:biber}]
+Process bibliography using the \texttt{biber} command.
+\item[\texttt{Make:bibtex}]
+Process bibliography using the \texttt{bibtex} command.
+\item[\texttt{Make:xindy}]
+Generate index using Xindy index processor.
+\item[\texttt{Make:makeindex}]
+Generate index using the Makeindex command.
+\item[\texttt{Make:xindex}]
+Generate index using the Xindex command.
+\end{description}
+
 \hypertarget{file-matches}{%
 \subsection{File matches}\label{file-matches}}
 
-Another type of action which can be specified in the build file is
-\texttt{match}. It can be called on the generated files:
+\label{sec:postprocessing}
+
+Another type of action that can be specified in the build file is
+\texttt{Make:match}. It can be used to post-process the generated files:
 
 \begin{verbatim}
 Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}")
 \end{verbatim}
 
-It tests output file names with \texttt{Lua} pattern matching and on
-matched items will execute a command or a function, specified in the
-second argument. Commands may be specified as strings, the templates
-will be expanded, \texttt{\$\{var\_name\}} placeholders will be replaced
-with corresponding variables from the \texttt{parameters} table,
-described in the previous subsection. One additional variable is
-available: \texttt{filename}. It contains the name of the current output
-file.
-
 The above example will clean all output \texttt{HTML} files using the
 \texttt{tidy} command.
 
-If function is used instead, it will get two parameters. The first one
-is a current filename, the second one table with parameters.
+The \texttt{Make:match} action tests output filenames using a
+\texttt{Lua} pattern matching function.\\
+It executes a command or a function, specified in the second argument,
+on files whose filenames match the pattern.
+
+The commands to be executed can be specified as strings. They can
+contain \texttt{\$\{var\_name\}} placeholders, which are replaced with
+corresponding variables from the \texttt{settings} table. The templating
+system was described in subsection \ref{sec:commandfunction}. There is
+an additional variable available in this table, called
+\texttt{filename}. It contains the name of the current output file.
+
+If a function is used instead, it will get two parameters. The first one
+is the current filename, the second one is the \texttt{settings} table.
+
+\begin{verbatim}
+Make:match("html$", function(filename, settings)
+  print("Post-processing file: ".. filename)
+  print("Available settings")
+  for k,v in pairs(settings)
+    print(k,v)
+  end
+  return true
+\end{verbatim}
+
+end)
+
+Multiple post-processing actions can be executed on each filename. The
+Lua action functions can return an exit code. If the exit code is false,
+the execution of the post-processing chain for the current file will be
+terminated.
 
 \hypertarget{filters}{%
 \subsubsection{Filters}\label{filters}}
 
-Some default \texttt{match} actions which can be used are available from
-the \texttt{make4ht-filter} module. It contains some functions which are
-useful for fixing some \texttt{tex4ht} bugs or shortcomings.
+\label{sec:filters}
 
-Example:
+To make it easier to post-process the generated files using the
+\texttt{match} actions, \texttt{make4ht} provides a filtering mechanism
+thanks to the \texttt{make4ht-filter} module.
+
+The \texttt{make4ht-filter} module returns a function that can be used
+for the filter chain building. Multiple filters can be chained into a
+pipeline. Each filter can modify the string that is passed to it from
+the previous filters. The changes are then saved to the processed file.
+
+Several built-in filters are available, it is also possible to create
+new ones.
+
+Example that use only the built-in filters:
 
 \begin{verbatim}
 local filter = require "make4ht-filter"
 local process = filter{"cleanspan", "fixligatures", "hruletohr"}
 Make:htlatex()
+Make:match("html$",process)
+\end{verbatim}
+
+Function \texttt{filter} accepts also function arguments, in this case
+this function takes file contents as a parameter and modified contents
+are returned.
+
+Example with custom filter:
+
+\begin{verbatim}
+local filter  = require "make4ht-filter"
+local changea = function(s) return s:gsub("a","z") end
+local process = filter{"cleanspan", "fixligatures", changea}
 Make:htlatex()
 Make:match("html$",process)
 \end{verbatim}
 
-The \texttt{make4ht-filter} module return a function which can be used
-for the filter chain building. Multiple filters can be chained, each of
-them can modify the string which was modified by the previous filters.
-The changes are then saved to the processed file.
+In this example, spurious span elements are joined, ligatures are
+decomposed, and then all letters ``a'' are replaced with ``z'' letters.
 
-Built-in filters are:
+Built-in filters are the following:
 
 \begin{description}
 \item[cleanspan]
@@ -389,16 +588,15 @@ alternative clean span filter, provided by Nat Kuhn
 decompose ligatures to base characters
 \item[hruletohr]
 \texttt{\textbackslash{}hrule} commands are translated to series of
-underscore characters by \texttt{tex4ht}, this filter translate these
+underscore characters by \TeX4ht, this filter translates these
 underscores to \texttt{\textless{}hr\textgreater{}} elements
 \item[entites]
-convert prohibited named entities to numeric entities (currently, only
-\texttt{\&nbsp;}, as it causes validation errors, and \texttt{tex4ht} is
-producing it sometimes)
+convert prohibited named entities to numeric entities (only
+\texttt{\&nbsp;} currently).
 \item[fix-links]
 replace colons in local links and \texttt{id} attributes with
 underscores. Some cross-reference commands may produce colons in
-internal links, which results in validation error.
+internal links, which results in a validation error.
 \item[mathjaxnode]
 use \href{https://github.com/pkra/mathjax-node-page/}{mathjax-node-page}
 to convert from MathML code to HTML + CSS or SVG. See
@@ -407,39 +605,22 @@ to convert from MathML code to HTML + CSS or SVG. See
 use styles from another \texttt{ODT} file serving as a template in the
 current document. It works for the \texttt{styles.xml} file in the
 \texttt{ODT} file. During the compilation, this file is named as
-\texttt{\textbackslash{}jobname.4oy}.
+\texttt{\textbackslash{}jobname.4oy}. \label{sec:odttemplate}
 \item[staticsite]
-create HTML files in format suitable for static site generators such as
-\href{https://jekyllrb.com/}{Jekyll}
+create HTML files in a format suitable for static site generators such
+as \href{https://jekyllrb.com/}{Jekyll}
 \item[svg-height]
 some SVG images produced by \texttt{dvisvgm} seem to have wrong
 dimensions. This filter tries to set the correct image size.
 \end{description}
 
-Function \texttt{filter} accepts also function arguments, in this case
-this function takes file contents as a parameter and modified contents
-are returned.
-
-Example:
-
-\begin{verbatim}
-local filter  = require "make4ht-filter"
-local changea = function(s) return s:gsub("a","z") end
-local process = filter{"cleanspan", "fixligatures", changea}
-Make:htlatex()
-Make:htlatex()
-Make:match("html$",process)
-\end{verbatim}
-
-In this example, spurious span elements are joined, ligatures are
-decomposed, and then all letters `a' are replaced with `z' letters.
-
 \hypertarget{dom-filters}{%
 \subsubsection{DOM filters}\label{dom-filters}}
 
-DOM filters use the \href{https://ctan.org/pkg/luaxml}{\texttt{LuaXML}}
-library to modify directly the XML object. This enables more powerful
-operations than the regex based filters from the previous section.
+DOM filters are variants of filters that use the
+\href{https://ctan.org/pkg/luaxml}{\texttt{LuaXML}} library to modify
+directly the XML object. This enables more powerful operations than the
+regex-based filters from the previous section.
 
 Example:
 
@@ -455,7 +636,10 @@ Available DOM filters:
 \item[aeneas]
 \href{https://www.readbeyond.it/aeneas/}{Aeneas} is a tool for
 automagical synchronization of text and audio. This filter modifies the
-HTML code to support the synchronization.
+HTML code to support synchronization.
+\item[collapsetoc]
+collapse table of contents to contain only top-level sectioning level
+and sections on the current page.
 \item[fixinlines]
 put all inline elements which are direct children of the
 \texttt{\textless{}body\textgreater{}} elements to a paragraph.
@@ -464,198 +648,65 @@ replace the colon (\texttt{:}) character in internal links and
 \texttt{id} attributes. They cause validation issues.
 \item[joincharacters]
 join consecutive \texttt{\textless{}span\textgreater{}} or
-\texttt{\textless{}mn\textgreater{}} elements.
+\texttt{\textless{}mn\textgreater{}} elements. This DOM filter
+supersedes the \texttt{cleanspan} filter.
 \item[joincolors]
 many \texttt{\textless{}span\textgreater{}} elements with unique
-\texttt{id} attribute are created when \LaTeX~colors are being used in
-the document. CSS rule is added for each of these elements, which may
-result in substantial grow of the CSS file. This filter replace these
+\texttt{id} attributes are created when \LaTeX~colors are being used in
+the document. A CSS rule is added for each of these elements, which may
+result in substantial growth of the CSS file. This filter replaces these
 rules with a common one for elements with the same color value.
 \item[odtimagesize]
 set correct dimensions for images in the ODT format. It is loaded by
 default for the ODT output.
+\item[odtpartable]
+resolve tables nested inside paragraphs, which is invalid in the ODT
+format.
+\item[tablerows]
+remove spurious rows from HTML tables.
 \item[t4htlinks]
 fix hyperlinks in the ODT format.
 \end{description}
 
-\hypertarget{make4ht-aeneas-config-package}{%
-\subsubsection{make4ht-aeneas-config
-package}\label{make4ht-aeneas-config-package}}
-
-Companion for the \texttt{aeneas} DOM filter is the
-\texttt{make4ht-aeneas-config} plugin. It can be used to write Aeneas
-configuration file or execute Aeneas on the generated HTML files.
-
-Available functions:
-
-\begin{description}
-\item[write\_job(parameters)]
-write Aenas job configuration to \texttt{config.xml} file. See the
-\href{https://www.readbeyond.it/aeneas/docs/clitutorial.html\#processing-jobs}{Aeneas
-documentation} for more information about jobs.
-\item[execute(parameters)]
-execute Aeneas.
-\item[process\_files(parameters)]
-process the audio and generated subtitle files.
-\end{description}
-
-By default, the \texttt{smil} file is created. It is assumed that there
-is audio file in \texttt{mp3} format named as the TeX file. It is
-possible to use different formats and file names using mapping.
-
-The configuration options can be passed directly to the functions or set
-using \texttt{filter\_settings\ "aeneas-config"\ \{parameters\}}
-function.
-
-Available parameters:
-
-\begin{description}
-\item[lang]
-document language. It is interfered from the HTML file, so it is not
-necessary to set it.
-\item[map]
-mapping between HTML, audio and subtitle files. More info bellow.
-\item[text\_type]
-type of the input. The \texttt{aeneas} DOM filter produces
-\texttt{unparsed} text type.
-\item[id\_sort]
-sorting of id attributes. Default value is \texttt{numeric}.
-\item[id\_regex]
-regular expression to parse the id attributes.
-\item[sub\_format]
-generated subtitle format. Default \texttt{smil}.
-\end{description}
-
-Additional parameters for the job configuration file:
-
-\begin{itemize}
-\tightlist
-\item
-  description
-\item
-  prefix
-\item
-  config\_name
-\item
-  keep\_config
-\end{itemize}
-
-It is possible to generate multiple HTML files from the LaTeX source.
-For example, \texttt{tex4ebook} generates separate file for each chapter
-or section. It is possible to set options for each HTML file, in
-particular names of the corresponding audio files. This mapping is done
-using \texttt{map} parameter.
-
-Example:
-
-\begin{verbatim}
-filter_settings "aeneas-config" {
-  map = {
-    ["sampleli1.html"] = {audio_file="sample.mp3"}, 
-    ["sample.html"] = false
-  }
-}
-\end{verbatim}
-
-Table keys are the configured file names. It is necessary to insert them
-as \texttt{{[}"filename.html"{]}}, because of Lua syntax rules.
-
-This example maps audio file \texttt{sample.mp3} to a section subpage.
-The main HTML file, which may contain title and table of contents
-doesn't have a corresponding audio file.
-
-Filenames of the sub files corresponds to the chapter numbers, so they
-are not stable when a new chapter is added. It is possible to request
-file names interfered from the chapter titles using the
-\texttt{sec-filename} option or \texttt{tex4ht}.
-
-Available \texttt{map} options:
-
-\begin{description}
-\item[audio\_file]
-the corresponding audio file
-\item[sub\_file]
-name of the generated subtitle file
-\end{description}
-
-The following options are same as their counter-parts from the main
-parameters table and generally don't need to be set:
-
-\begin{itemize}
-\tightlist
-\item
-  prefix
-\item
-  file\_desc
-\item
-  file\_id
-\item
-  text\_type
-\item
-  id\_sort
-\item
-  id\_prefix
-\item
-  sub\_format
-\end{itemize}
-
-Full example:
-
-\begin{verbatim}
-local domfilter = require "make4ht-domfilter"
-local aeneas_config = require "make4ht-aeneas-config"
-
-filter_settings "aeneas-config" {
-  map = {
-    ["krecekli1.xhtml"] = {audio_file="krecek.mp3"}, 
-    ["krecek.xhtml"] = false
-  }
-}
-
-local process = domfilter {"aeneas"}
-Make:match("html$", process)
-
-if mode == "draft" then
-  aeneas_config.process_files {}
-else
-  aeneas_config.execute {}
-end
-\end{verbatim}
-
 \hypertarget{image-conversion}{%
 \subsection{Image conversion}\label{image-conversion}}
 
-It is possible to convert parts of LaTeX input to pictures, it is used
-for example for math or diagrams in \texttt{tex4ht}.
+\label{sec:imageconversion}
 
-These pictures are stored in a special \texttt{dvi} file, which can be
-processed by the \texttt{dvi\ to\ image} commands.
+It is possible to convert parts of the \LaTeX~input as pictures. It can
+be used for preserving the appearance of math or diagrams, for example.
 
-This conversion is normally configured in the \texttt{env\ file}, which
-is system dependent and which has a bit unintuitive syntax. This
-configuration is processed by the \texttt{t4ht} application and
-conversion commands are called for all pictures.
+These pictures are stored in a special \texttt{DVI} file, which can be
+processed by a \texttt{DVI} to image commands, such as \texttt{dvipng}
+or \texttt{dvisvgm}.
+
+This conversion is normally configured in the \texttt{tex4ht.env} file.
+This file is system dependent and it has quite an unintuitive syntax.
+The configuration is processed by the \texttt{t4ht} application and the
+conversion command is called for all pictures.
 
 It is possible to disable \texttt{t4ht} image processing and configure
-image conversion in the build file:
+image conversion in the build file using the \texttt{image} action:
 
 \begin{verbatim}
 Make:image("png$",
 "dvipng -bg Transparent -T tight -o ${output}  -pp ${page} ${source}")
 \end{verbatim}
 
-\texttt{Make:image} takes two parameters, pattern to match image name
-and action. Action can be either string template with conversion
-command, or function which takes a table with parameters as an argument.
+\texttt{Make:image} takes two parameters, a \texttt{Lua} pattern to
+match the image name, and the action.
+
+Action can be either a string template with the conversion command or a
+function that takes a table with parameters as an argument.
 
 There are three parameters:
 
 \begin{itemize}
 \tightlist
 \item
-  \texttt{output} - output image file name
+  \texttt{output} - output image filename
 \item
-  \texttt{source} - \texttt{dvi} file with the pictures
+  \texttt{source} - \texttt{DVI} file with the pictures
 \item
   \texttt{page} - page number of the converted image
 \end{itemize}
@@ -664,9 +715,9 @@ There are three parameters:
 \subsection{\texorpdfstring{The \texttt{mode}
 variable}{The mode variable}}\label{the-mode-variable}}
 
-There is global \texttt{mode} variable available in the build file. It
-contains contents of the \texttt{-\/-mode} command line option. It can
-be used to run some commands conditionally. For example:
+The \texttt{mode} variable available in the build process contains
+contents of the \texttt{-\/-mode} command line option. It can be used to
+run some commands conditionally. For example:
 
 \begin{verbatim}
  if mode == "draft" then
@@ -679,8 +730,8 @@ be used to run some commands conditionally. For example:
 \end{verbatim}
 
 In this example (which is the default configuration used by
-\texttt{make4ht}), LaTeX is called only once when \texttt{make4ht} is
-called with \texttt{draft} mode:
+\texttt{make4ht}), \LaTeX~is called only once when \texttt{make4ht} is
+called with the \texttt{draft} mode:
 
 \begin{verbatim}
 make4ht -m draft filename
@@ -690,10 +741,12 @@ make4ht -m draft filename
 \subsection{\texorpdfstring{The \texttt{settings}
 table}{The settings table}}\label{the-settings-table}}
 
-You may want to access to the parameters also outside commands, file
-matches and image conversion functions. For example, if you want to
-convert your file to the \texttt{OpenDocument\ Format\ (ODT)}, you can
-use the following settings, based on the \texttt{oolatex} command:
+\label{sec:settings}
+
+It is possible to access the parameters outside commands, file matches
+and image conversion functions. For example, to convert the document to
+the \texttt{OpenDocument\ Format\ (ODT)}, the following settings can be
+used. They are based on the \texttt{oolatex} command:
 
 \begin{verbatim}
 settings.tex4ht_sty_par = settings.tex4ht_sty_par ..",ooffice"
@@ -701,7 +754,11 @@ settings.tex4ht_par = settings.tex4ht_par .. " ooffice/! -cmozhtf"
 settings.t4ht_par = settings.t4ht_par .. " -cooxtpipes -coo "
 \end{verbatim}
 
-There are some functions to ease access to the settings:
+(Note that it is possible to use the \texttt{-\/-format\ odt} option
+which is superior to the previous code. This example is intended just as
+an illustration)
+
+There are some functions to simplify access to the settings:
 
 \begin{description}
 \item[\texttt{set\_settings\{parameters\}}]
@@ -714,8 +771,8 @@ set settings for a filter
 get settings for a filter
 \end{description}
 
-Using these functions, it is possible to simplify the settings for the
-\texttt{ODT} format:
+For example, it is possible to simplify the sample from the previous
+code listings:
 
 \begin{verbatim}
 settings_add {
@@ -734,8 +791,8 @@ filter_settings "test" {
 }
 \end{verbatim}
 
-These settings can be read in the extensions and filters using
-\texttt{get\_filter\_settings}:
+These settings can be retrieved in the extensions and filters using the
+\texttt{get\_filter\_settings} function:
 
 \begin{verbatim}
 function test(input)
@@ -746,14 +803,153 @@ end
    
 \end{verbatim}
 
+\hypertarget{default-settings}{%
+\subsubsection{Default settings}\label{default-settings}}
+
+The default parameters are the following:
+
+\begin{description}
+\item[\texttt{htlatex}]
+used \TeX~engine
+\item[\texttt{input}]
+content of \texttt{\textbackslash{}jobname}, see also the
+\texttt{tex\_file} parameter.
+\item[\texttt{interaction}]
+interaction mode for the \TeX~engine. The default value is
+\texttt{batchmode} to suppress user input on compilation errors. It also
+suppresses most of the \TeX~ compilation log output. Use the
+\texttt{errorstopmode} for the default behavior.
+\item[\texttt{tex\_file}]
+input \TeX~filename
+\item[\texttt{latex\_par}]
+command line parameters to the \TeX~engine
+\item[\texttt{packages}]
+additional \LaTeX~code inserted before
+\texttt{\textbackslash{}documentclass}. Useful for passing options to
+packages used in the document or to load additional packages.
+\item[\texttt{tex4ht\_sty\_par}]
+options for \texttt{tex4ht.sty}
+\item[\texttt{tex4ht\_par}]
+command line options for the \texttt{tex4ht} command
+\item[\texttt{t4ht\_par}]
+command line options for the \texttt{t4ht} command
+\item[\texttt{outdir}]
+the output directory
+\item[\texttt{correct\_exit}]
+expected \texttt{exit\ code} from the command. The compilation will be
+terminated if the exit code of the executed command has a different
+value.
+\end{description}
+
+\hypertarget{configfile}{%
+\section{Configuration file}\label{configfile}}
+
+It is possible to globally modify the build settings using the
+configuration file. It is a special version of a build file where the
+global settings can be set.
+
+Common tasks for the configuration file can be a declaration of the new
+commands, loading of the default filters or specification of a default
+build sequence.
+
+One additional functionality not available in the build files are
+commands for enabling and disabling of extensions.
+
+\hypertarget{location}{%
+\subsection{Location}\label{location}}
+
+The configuration file can be saved either in the
+\texttt{\$HOME/.config/make4ht/config.lua} file, or in the
+\texttt{.make4ht} file placed in the current directory or it's parent
+directories (up to the \texttt{\$HOME} directory).
+
+\hypertarget{additional-commands}{%
+\subsection{Additional commands}\label{additional-commands}}
+
+There are two additional commands:
+
+\begin{description}
+\item[\texttt{Make:enable\_extension(name)}]
+require extension
+\item[\texttt{Make:disable\_extension(name)}]
+disable extension
+\end{description}
+
+\hypertarget{example}{%
+\subsection{Example}\label{example}}
+
+The following example of the configuration file adds support for the
+\texttt{biber} command, requires \texttt{common\_domfilters} extension
+and requires MathML output for math.
+
+\begin{verbatim}
+Make:add("biber", "biber ${input}")
+Make:enable_extension "common_domfilters"
+settings_add {
+  tex4ht_sty_par =",mathml"
+}
+\end{verbatim}
+
 \hypertarget{list-of-available-settings-for-filters-and-extensions.}{%
-\subsection{List of available settings for filters and
+\section{List of available settings for filters and
 extensions.}\label{list-of-available-settings-for-filters-and-extensions.}}
 
-These settings may be set using \texttt{filter\_settings} function.
+These settings may be set using \texttt{filter\_settings} function in a
+build file or in the \texttt{make4ht} configuration file.
+
+\hypertarget{indexing-commands}{%
+\subsection{Indexing commands}\label{indexing-commands}}
+
+The indexing commands (like \texttt{xindy} or \texttt{makeindex}) use
+some common settings.
+
+\begin{description}
+\item[idxfile]
+name of the \texttt{.idx} file. Default value is
+\texttt{\textbackslash{}jobname.idx}.
+\item[indfile]
+name of the \texttt{.ind} file. Default value is the same as
+\texttt{idxfile} with the file extension changed to \texttt{.ind}.
+\end{description}
+
+Each indexing command can have some additional settings.
+
+\hypertarget{the-xindy-command}{%
+\subsubsection{\texorpdfstring{The \texttt{xindy}
+command}{The xindy command}}\label{the-xindy-command}}
+
+\begin{description}
+\item[encoding]
+text encoding of the \texttt{.idx} file. Default value is \texttt{utf8}.
+\item[language]
+index language. Default language is English.
+\item[modules]
+table with names of additional \texttt{Xindy} modules to be used.
+\end{description}
+
+\hypertarget{the-makeindex-command}{%
+\subsubsection{\texorpdfstring{The \texttt{makeindex}
+command}{The makeindex command}}\label{the-makeindex-command}}
+
+options
+
+: additional command line options for the Makeindex command.
+
+\hypertarget{the-xindex-command}{%
+\subsubsection{\texorpdfstring{The \texttt{xindex}
+command}{The xindex command}}\label{the-xindex-command}}
+
+options
+
+: additional command line options for the Xindex command.
+
+\begin{description}
+\item[language]
+document language
+\end{description}
 
 \hypertarget{the-tidy-extension}{%
-\subsubsection{\texorpdfstring{The \texttt{tidy}
+\subsection{\texorpdfstring{The \texttt{tidy}
 extension}{The tidy extension}}\label{the-tidy-extension}}
 
 \begin{description}
@@ -762,13 +958,37 @@ command line options for the \texttt{tidy} command. Default value is
 \texttt{-m\ -utf8\ -w\ 512\ -q}.
 \end{description}
 
+\hypertarget{the-collapsetoc-dom-filter}{%
+\subsection{\texorpdfstring{The \texttt{collapsetoc} dom
+filter}{The collapsetoc dom filter}}\label{the-collapsetoc-dom-filter}}
+
+\begin{description}
+\item[\texttt{toc\_query}]
+CSS selector for selecting the table of contents container.
+\item[\texttt{title\_query}]
+CSS selector for selecting all elements that contain the section ID
+attribute.
+\item[\texttt{toc\_levels}]
+table containing a hierarchy of classes used in TOC
+\end{description}
+
+Default values:
+
+\begin{verbatim}
+filter_settings "collapsetoc" {
+  toc_query = ".tableofcontents",
+  title_query = ".partHead a, .chapterHead a, .sectionHead a, .subsectionHead a",
+  toc_levels = {"partToc", "chapterToc", "sectionToc", "subsectionToc", "subsubsectionToc"}
+}
+\end{verbatim}
+
 \hypertarget{the-fixinlines-dom-filter}{%
-\subsubsection{\texorpdfstring{The \texttt{fixinlines} dom
+\subsection{\texorpdfstring{The \texttt{fixinlines} dom
 filter}{The fixinlines dom filter}}\label{the-fixinlines-dom-filter}}
 
 \begin{description}
 \item[inline\_elements]
-table of inline elements which shouldn't be direct descendants of the
+table of inline elements that shouldn't be direct descendants of the
 \texttt{body} element. The element names should be table keys, the
 values should be true.
 \end{description}
@@ -780,23 +1000,24 @@ filter_settings "fixinlines" {inline_elements = {a = true, b = true}}
 \end{verbatim}
 
 \hypertarget{the-joincharacters-dom-filter}{%
-\subsubsection{\texorpdfstring{The \texttt{joincharacters} dom
+\subsection{\texorpdfstring{The \texttt{joincharacters} dom
 filter}{The joincharacters dom filter}}\label{the-joincharacters-dom-filter}}
 
 \begin{description}
-\item[charelements]
-table of elements which should be joined if several instances with the
-same value of \texttt{class} attribute are side by side.
+\item[charclasses]
+table of elements that should be concatenated when two or more of such
+elements with the same value of the \texttt{class} attribute are placed
+one after another.
 \end{description}
 
 Example
 
 \begin{verbatim}
-filter_settings "joincharacters" { charclases = { span=true, mn = true}}
+filter_settings "joincharacters" { charclasses = { span=true, mn = true}}
 \end{verbatim}
 
 \hypertarget{mathjaxsettings}{%
-\subsubsection{\texorpdfstring{The \texttt{mathjaxnode}
+\subsection{\texorpdfstring{The \texttt{mathjaxnode}
 filter}{The mathjaxnode filter}}\label{mathjaxsettings}}
 
 \begin{description}
@@ -815,12 +1036,12 @@ filter_settings "mathjaxnode" {
 
 \begin{description}
 \item[cssfilename]
-\texttt{mjpage} puts some CSS code into the HTML pages.
+the \texttt{mjpage} command puts some CSS code into the HTML pages.
 \texttt{mathjaxnode} extracts this information and saves it to a
 standalone CSS file. Default CSS filename is \texttt{mathjax-chtml.css}
 \item[fontdir]
-directory with MathJax font files. This option enables use of local
-fonts, which is usefull in Epub conversion, for example. The font
+directory with MathJax font files. This option enables the use of local
+fonts, which is useful in the conversion to ePub, for example. The font
 directory should be sub-directory of the current directory. Only TeX
 font is supported at the moment.
 \end{description}
@@ -833,37 +1054,22 @@ filter_settings "mathjaxnode" {
 }
 \end{verbatim}
 
-\hypertarget{the-aeneas-filter}{%
-\subsubsection{\texorpdfstring{The \texttt{aeneas}
-filter}{The aeneas filter}}\label{the-aeneas-filter}}
-
-\begin{description}
-\item[skip\_elements]
-List of CSS selectors that match elements which shouldn't be processed.
-Default value: \texttt{\{\ "math",\ "svg"\}}.
-\item[id\_prefix]
-prefix used in the ID attribute forming.
-\item[sentence\_match]
-Lua pattern used to match a sentence. Default value:
-\texttt{"({[}\^{}\%.\^{}\%?\^{}!{]}*)({[}\%.\%?!{]}?)"}.
-\end{description}
-
 \hypertarget{the-staticsite-filter-and-extension}{%
-\subsubsection{\texorpdfstring{The \texttt{staticsite} filter and
+\subsection{\texorpdfstring{The \texttt{staticsite} filter and
 extension}{The staticsite filter and extension}}\label{the-staticsite-filter-and-extension}}
 
 \begin{description}
 \item[site\_root]
 directory where generated files should be copied.
 \item[map]
-table where keys are patterns that match filenames, value contains
-destination directoryfor matched files, relative to the
-\texttt{site\_root} (it is possible to use \texttt{..} to swich to
-parent directory).
+a hash table where keys contain patterns that match filenames and values
+contain destination directory for the matched files. The destination
+directories are relative to the \texttt{site\_root} (it is possible to
+use \texttt{..} to switch to a parent directory).
 \item[file\_pattern]
-pattern used for filename generation. It is possible to use string
-templates and format strings for \texttt{os.date} function. Default
-value of \texttt{\%Y-\%m-\%d-\$\{input\}} creates names in the form of
+a pattern used for filename generation. It is possible to use string
+templates and format strings for \texttt{os.date} function. The default
+pattern \texttt{\%Y-\%m-\%d-\$\{input\}} creates names in the form of
 \texttt{YYYY-MM-DD-file\_name}.
 \item[header]
 table with variables to be set in the YAML header in HTML files. If the
@@ -891,7 +1097,7 @@ filter_settings "staticsite" {
 \end{verbatim}
 
 \hypertarget{the-dvisvgm_hashes-extension}{%
-\subsubsection{\texorpdfstring{The \texttt{dvisvgm\_hashes}
+\subsection{\texorpdfstring{The \texttt{dvisvgm\_hashes}
 extension}{The dvisvgm\_hashes extension}}\label{the-dvisvgm_hashes-extension}}
 
 \begin{description}
@@ -899,18 +1105,18 @@ extension}{The dvisvgm\_hashes extension}}\label{the-dvisvgm_hashes-extension}}
 command line options for Dvisvgm. The default value is
 \texttt{-n\ -\/-exact\ -c\ 1.15,1.15}.
 \item[cpu\_cnt]
-number of processor cores used for conversion. The extension tries to
-detect the available cores automatically by default.
+the number of processor cores used for the conversion. The extension
+tries to detect the available cores automatically by default.
 \item[parallel\_size]
-number of pages used in each Dvisvgm call. The extension detects changed
-pages in the DVI file and construct multiple calls to Dvisvgm with only
-changed pages.
+the number of pages used in each Dvisvgm call. The extension detects
+changed pages in the DVI file and constructs multiple calls to Dvisvgm
+with only changed pages.
 \item[scale]
 SVG scaling.
 \end{description}
 
 \hypertarget{the-odttemplate-filter-and-extension}{%
-\subsubsection{\texorpdfstring{The \texttt{odttemplate} filter and
+\subsection{\texorpdfstring{The \texttt{odttemplate} filter and
 extension}{The odttemplate filter and extension}}\label{the-odttemplate-filter-and-extension}}
 
 \begin{description}
@@ -920,108 +1126,175 @@ filename of the template \texttt{ODT} file
 
 \texttt{odttemplate} can also get the template filename from the
 \texttt{odttemplate} option from \texttt{tex4ht\_sty\_par} parameter. It
-can be set useing following command line call, for example:
+can be set using the following command line call:
 
 \begin{verbatim}
  make4ht -f odt+odttemplate filename.tex "odttemplate=template.odt"
 \end{verbatim}
 
-\hypertarget{configfile}{%
-\section{Configuration file}\label{configfile}}
+\hypertarget{the-aeneas-filter}{%
+\subsection{\texorpdfstring{The \texttt{aeneas}
+filter}{The aeneas filter}}\label{the-aeneas-filter}}
 
-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.
+\begin{description}
+\item[skip\_elements]
+List of CSS selectors that match elements that shouldn't be processed.
+Default value: \texttt{\{\ "math",\ "svg"\}}.
+\item[id\_prefix]
+prefix used in the ID attribute forming.
+\item[sentence\_match]
+Lua pattern used to match a sentence. Default value:
+\texttt{"({[}\^{}\%.\^{}\%?\^{}!{]}*)({[}\%.\%?!{]}?)"}.
+\end{description}
 
-\hypertarget{location}{%
-\subsection{Location}\label{location}}
+\hypertarget{the-make4ht-aeneas-config-package}{%
+\subsection{\texorpdfstring{The \texttt{make4ht-aeneas-config}
+package}{The make4ht-aeneas-config package}}\label{the-make4ht-aeneas-config-package}}
 
-The configuration file can be saved either in
-\texttt{\$HOME/.config/make4ht/config.lua} or in \texttt{.make4ht} in
-the current directory or it's parents (up to \texttt{\$HOME}).
+Companion for the \texttt{aeneas} DOM filter is the
+\texttt{make4ht-aeneas-config} plugin. It can be used to write the
+Aeneas configuration file or execute Aeneas on the generated HTML files.
 
-\hypertarget{additional-commands}{%
-\subsection{Additional commands}\label{additional-commands}}
+Available functions:
 
-There are two additional commands:
+\begin{description}
+\item[write\_job(parameters)]
+write Aenas job configuration to \texttt{config.xml} file. See the
+\href{https://www.readbeyond.it/aeneas/docs/clitutorial.html\#processing-jobs}{Aeneas
+documentation} for more information about jobs.
+\item[execute(parameters)]
+execute Aeneas.
+\item[process\_files(parameters)]
+process the audio and generated subtitle files.
+\end{description}
+
+By default, a \texttt{SMIL} file is created. It is assumed that there is
+an audio file in the \texttt{mp3} format, named as the \TeX~file. It is
+possible to use different formats and filenames using mapping.
+
+The configuration options can be passed directly to the functions or set
+using \texttt{filter\_settings\ "aeneas-config"\ \{parameters\}}
+function.
+
+\hypertarget{available-parameters}{%
+\subsubsection{Available parameters}\label{available-parameters}}
 
 \begin{description}
-\item[\texttt{Make:enable\_extension(name)}]
-require extension
-\item[\texttt{Make:disable\_extension(name)}]
-disable extension
+\item[lang]
+document language. It is interfered from the HTML file, so it is not
+necessary to set it.
+\item[map]
+mapping between HTML, audio and subtitle files. More info below.
+\item[text\_type]
+type of input. The \texttt{aeneas} DOM filter produces an
+\texttt{unparsed} text type.
+\item[id\_sort]
+sorting of id attributes. The default value is \texttt{numeric}.
+\item[id\_regex]
+regular expression to parse the id attributes.
+\item[sub\_format]
+generated subtitle format. The default value is \texttt{smil}.
 \end{description}
 
-\hypertarget{example}{%
-\subsection{Example}\label{example}}
+\hypertarget{additional-parameters-for-the-job-configuration-file}{%
+\subsubsection{Additional parameters for the job configuration
+file}\label{additional-parameters-for-the-job-configuration-file}}
+
+\begin{itemize}
+\tightlist
+\item
+  description
+\item
+  prefix
+\item
+  config\_name
+\item
+  keep\_config
+\end{itemize}
 
-The following configuration add support for the \texttt{biber} command,
-requires \texttt{common\_domfilters} extension and requires MathML
-output for math.
+It is possible to generate multiple HTML files from the \LaTeX~source.
+For example, \texttt{tex4ebook} generates a separate file for each
+chapter or section. It is possible to set options for each HTML file, in
+particular names of the corresponding audio files. This mapping is done
+using the \texttt{map} parameter.
+
+Example:
 
 \begin{verbatim}
-Make:add("biber", "biber ${input}")
-Make:enable_extension "common_domfilters"
-settings_add {
-  tex4ht_sty_par =",mathml"
+filter_settings "aeneas-config" {
+  map = {
+    ["sampleli1.html"] = {audio_file="sample.mp3"}, 
+    ["sample.html"] = false
+  }
 }
 \end{verbatim}
 
-\hypertarget{command-line-options}{%
-\section{Command line options}\label{command-line-options}}
+Table keys are the configured filenames. It is necessary to insert them
+as \texttt{{[}"filename.html"{]}}, because of Lua syntax rules.
 
-\begin{verbatim}
-make4ht - build system for tex4ht
-Usage:
-make4ht [options] filename ["tex4ht.sty op." "tex4ht op." 
-     "t4ht op" "latex op"]
--b,--backend (default tex4ht) Backend used for xml generation.
-     possible values: tex4ht or lua4ht
--c,--config (default xhtml) Custom config file
--d,--output-dir (default "")  Output directory
--e,--build-file (default nil)  If build file name is different 
-     than `filename`.mk4
--f,--format  (default nil)  Output file format
--l,--lua  Use lualatex for document compilation
--m,--mode (default default) Switch which can be used in the makefile
--n,--no-tex4ht  Disable dvi file processing with tex4ht command
--s,--shell-escape Enables running external programs from LaTeX
--u,--utf8  For output documents in utf8 encoding
--v,--version  Print version number
--x,--xetex Use xelatex for document compilation
-<filename> (string) Input file name
-\end{verbatim}
+This example maps audio file \texttt{sample.mp3} to a section subpage.
+The main HTML file, which may contain title and table of contents
+doesn't have a corresponding audio file.
 
-You can still invoke \texttt{make4ht} in the same way as
-\texttt{htlatex}:
+Filenames of the subfiles correspond to the chapter numbers, so they are
+not stable when a new chapter is added. It is possible to request
+filenames derived from the chapter titles using the
+\texttt{sec-filename} option for \texttt{tex4ht.sty}.
 
-\begin{verbatim}
-make4ht filename "customcfg, charset=utf-8" "-cunihtf -utf8" "-dfoo"
-\end{verbatim}
+\hypertarget{available-map-options}{%
+\subsubsection{\texorpdfstring{Available \texttt{map}
+options}{Available map options}}\label{available-map-options}}
 
-Note that this will not use \texttt{make4ht} routines for output
-directory making and copying. If you want to use them, change the line
-above to:
+\begin{description}
+\item[audio\_file]
+the corresponding audio file
+\item[sub\_file]
+name of the generated subtitle file
+\end{description}
 
-\begin{verbatim}
-make4ht -d foo filename "customcfg, charset=utf-8" "-cunihtf -utf8"
-\end{verbatim}
+The following options are the same as their counterparts from the main
+parameters table and generally, don't need to be set:
 
-This call has the same effect as the following:
+\begin{itemize}
+\tightlist
+\item
+  prefix
+\item
+  file\_desc
+\item
+  file\_id
+\item
+  text\_type
+\item
+  id\_sort
+\item
+  id\_prefix
+\item
+  sub\_format
+\end{itemize}
+
+\hypertarget{full-example}{%
+\subsubsection{Full example}\label{full-example}}
 
 \begin{verbatim}
-make4ht -u -c customcfg -d foo filename
-\end{verbatim}
+local domfilter = require "make4ht-domfilter"
+local aeneas_config = require "make4ht-aeneas-config"
 
-Output directory doesn't have to exist, it will be created
-automatically. Specified path can be relative to current directory, or
-absolute:
+filter_settings "aeneas-config" {
+  map = {
+    ["krecekli1.xhtml"] = {audio_file="krecek.mp3"}, 
+    ["krecek.xhtml"] = false
+  }
+}
 
-\begin{verbatim}
-make4ht -d use/current/dir/ filename
-make4ht -d ../gotoparrentdir filename
-make4ht -d ~/gotohomedir filename
-make4ht -d c:\documents\windowspathsareworkingtoo filename
+local process = domfilter {"aeneas"}
+Make:match("html$", process)
+
+if mode == "draft" then
+  aeneas_config.process_files {}
+else
+  aeneas_config.execute {}
+end
 \end{verbatim}
 
 \hypertarget{troubleshooting}{%
@@ -1041,23 +1314,23 @@ make4ht:unrecognized parameter: i
 It may be caused by a following \texttt{make4ht} invocation:
 
 \begin{verbatim}
-make4ht hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8" -d foo
+$ make4ht hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8" -d foo
 \end{verbatim}
 
 The command line option parser is confused by mixing options for
-\texttt{make4ht} and \texttt{tex4ht} in this case and tries to interpret
-the \texttt{-cunihtf\ -utf8}, which are options for \texttt{tex4ht}
-command as \texttt{make4ht} options. To fix that, you can either move
-the \texttt{-d\ foo} directly after \texttt{make4ht} command:
+\texttt{make4ht} and \TeX4ht~in this case. It tries to interpret the
+\texttt{-cunihtf\ -utf8}, which are options for the \texttt{tex4ht}
+command, as \texttt{make4ht} options. To fix that, try to move the
+\texttt{-d\ foo} directly after the \texttt{make4ht} command:
 
 \begin{verbatim}
-make4ht -d foo hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8"
+$ make4ht -d foo hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8"
 \end{verbatim}
 
-Another option is to add a space before \texttt{tex4ht} options:
+Another option is to add a space before the \texttt{tex4ht} options:
 
 \begin{verbatim}
-make4ht hello.tex "customcfg,charset=utf-8" " -cunihtf -utf8" -d foo
+$ make4ht hello.tex "customcfg,charset=utf-8" " -cunihtf -utf8" -d foo
 \end{verbatim}
 
 The former way is preferable, though.
@@ -1066,10 +1339,10 @@ The former way is preferable, though.
 \subsection{Filenames containing
 spaces}\label{filenames-containing-spaces}}
 
-\texttt{tex4ht} cannot handle filenames containing spaces.
-\texttt{make4ht} thus replaces spaces in input file names with
-underscores, so generated XML files use underscores instead of spaces as
-well.
+\texttt{tex4ht} command cannot handle filenames containing spaces. to
+fix this issue, \texttt{make4ht} replaces spaces in the input filenames
+with underscores. The generated XML filenames use underscores instead of
+spaces as well.
 
 \hypertarget{filenames-containing-non-ascii-characters}{%
 \subsection{Filenames containing non-ASCII