make4ht (9apr18)

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

13 files changed, 1840 insertions, 283 deletions

diff --git a/Master/texmf-dist/doc/support/make4ht/README b/Master/texmf-dist/doc/support/make4ht/README
index 9d7c10c75b4..924456189d8 100644
--- a/Master/texmf-dist/doc/support/make4ht/README
+++ b/Master/texmf-dist/doc/support/make4ht/README
@@ -1,175 +1,320 @@
+% [![Build Status](https://travis-ci.org/michal-h21/make4ht.svg?branch=master)](https://travis-ci.org/michal-h21/make4ht)
+
 # Introduction
 
-`make4ht` is a simple build system for tex4ht. It is both executable which
-simplifies `tex4ht` execution and a library which can be used to create
-customized conversion programs. An example of such conversion program is [tex4ebook](https://github.com/michal-h21/tex4ebook)
+`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
+ePub and other e-book formats.
 
-## License
 
-Permission is granted to copy, distribute and/or modify this software
-under the terms of the LaTeX Project Public License, version 1.3.
+## How it works
+
+### The issues with default `tex4ht` conversion commands
 
-How it works
-------------
 
-Default compilation script for `tex4ht`, named `htlatex`  compiles LaTeX files to `HTML` with this command  sequence:
+`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. The `DVI` file is then processed and 
+desired output files are created.
+
+The basic command provided by `tex4ht` 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 options filename
-    t4ht options filename
-
-The problem is that this is inefficient when  you need to run program which
-interact with LaTeX, such as `Makeindex` or `Bibtex`. In that case, you need to
-create new script based on the default one, or run `htlatex` twice, which means
-six LaTeX runs. 
-
-Another problem is with `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 some subdirectory, they will be copied to the output directory,
-but links will be pointing to non existing subdirectory.
-
-Image conversion is directed with the 
-[env file](http://www.tug.org/applications/tex4ht/mn35.html#index35-73001), 
-with really strange syntax based on whitespace and 
+    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"
+
+For basic `HTML` conversion it is possible to use the most basic invocation:
+
+    htlatex filename.tex
+
+It can be much more involved for `HTML 5` output in `UTF-8` encoding:
+
+    htlatex filename.tex "xhtml,html5,charset=utf-8" "-cmozhtf -utf8"
+
+`make4ht` can simplify it:
+
+    make4ht -uf html5 filename.tex
+
+Another issue is the fixed compilation order and 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 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 -um draft -f html5 filename.tex
+
+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.
+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
+
+
+
+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).
+`make4ht` provides simpler means for the image conversion in the build files.
+
 With `make4ht` build files, we have simple mean to fix these issues. We can
-change image conversion parameters without need to modify the `env file`,
-and call actions on the output files. These actions can be either external
+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 build script are written.
+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
+format can be requested using the `--format` option. Supported formats are:
+
+ - `xhtml`
+ - `html5`
+ - `odt`
+
+The `--format` option can be also used for extension loading.
+
+## Extensions
 
+Extensions can be used to modify the build process without the need to use a build file. They
+may post-process the output files or request additional commands for the compilation.
+
+The extensions can be enabled or disabled by appending `+EXTENSION` or `-EXTENSION` after
+the output format name:
+
+     make4ht -uf html5+tidy filename.tex
+
+Available extensions:
+
+latexmk
+
+:    use `Latexmk` for \LaTeX\ compilation.
+
+tidy
+
+:    clean the `HTML` files using the `tidy` command.
+
+common\_filters
+
+:    clean the output HTML files using 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`.
+
+mathjaxnode
+
+:    use [mathjax-node-page](https://github.com/pkra/mathjax-node-page/) to
+     convert from MathML code to HTML + CSS or SVG. See [the available
+     settings](#mathjaxsettings).
 
 # Build files
 
-## Commands
+`make4ht` supports build files. These are `Lua` scripts which can adjust
+the build process. You can request external applications like `bibtex` or `makeindex`,
+pass options to the commands, modify the image conversion process, or post-process the
+generated files.
 
-By default, build file is saved in file named `filename + .mk4 extension`.
+`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
 option.
 
-Sample:
+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, `tidy` command is executed on the output `html` file.
+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.
 
 Note that you don't have to call `tex4ht` and `t4ht` commands explicitly in the
 build file, they are called automatically. 
 
-You can add more commands like `Make:htlatex` with 
+## User commands
+
+You can add more commands like `Make:htlatex` using `Make:add` command:
 
     Make:add("name", "command", {parameters}, repetition)
 
+The `name` and `command` parameters are required, rest of the parameters are optional.
 
-it can be called with
+This defines `name` command, which can be then executed as `Make:name()` command.
 
-    Make:name()
+### Provided commands
 
-`command` can be text template, or function:
+`Make:htlatex`
 
-    Make:add("text", "hello, input file: ${input}")
+:    One call to TeX engine with special configuration for `tex4ht` loading.
+
+`Make:latexmk`
+
+:    Use `Latexmk` for the document compilation. `tex4ht` will be loaded automatically.
+
+`Make:tex4ht`
+
+:    Process the `DVI` file and creates the output files.
+
+`Make:t4ht`
+
+:    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) 
       for k, v in pairs(params) do 
         print(k..": "..v) 
-      end
+      end, {custom="Hello world"}
     )
 
-`parameters` is a table or `nil` value.
+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. 
 
-Default parameters are:
+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.
 
-htlatex 
+
+
+The default parameters are following:
+
+`htlatex`
 
 :     used compiler
 
-input 
+`input`
 
 :    it is output file name in fact
 
-tex_file
+`tex_file`
 
 :    input TeX file
 
-latex_par 
+`latex_par`
 
 :    parameters to `latex`
 
-packages
+`packages`
 
-:    insert additionl LaTeX code which is inserted before `\documentclass`.
+:    insert additional LaTeX code which is inserted before `\documentclass`.
      Useful for passing options to packages or additional packages loading
 
-tex4ht_sty_par 
+`tex4ht_sty_par`
 
 :    parameters to `tex4ht.sty`
 
-tex4ht_par 
+`tex4ht_par`
 
-:     parameters to `tex4ht` application
+:     parameters to the `tex4ht` application
 
-t4ht_par 
+`t4ht_par`
 
-:    parameters to `t4ht` application
+:    parameters to the `t4ht` application
 
-outdir 
+`outdir`
 
-:     output directory
+:    the output directory
 
-repetition 
+`repetition`
 
 :    limit number of command execution.
 
-correct_exit 
+`correct_exit`
+
+:    expected `exit code` from the command. The compilation will be terminated
+     if the command `exit code` is different.
 
-:    expected `exit code` from the command. The compilation will be terminted
-     when the command `exit code` is different.
 
+### Repetition
 
-You may add your own parameters, they will be accessible in templates and
-functions.
+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.
 
-With `repetition`, you can limit number of command executions.  Its value
-should be number or `nil`.  This is used in the case of `tex4ht` and `t4ht`
-commands, as they should be executed only once and they would be executed
-multiple times if you include them in the build file, because they would be
-called also by `make4ht`. With `repetition`, second execution is blocked.
+### Expected exit code
 
-You can set expected exit code from a command with `correct_exit`. Compilation
-is stopped when command returns different exit code. The situation is 
-different 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.
+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. 
+
+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.
 
 ## File matches
 
-Other type of action which can be specified in the build file are
-matches  which may be called  on the generated files:
+Another type of action which can be specified in the build file is
+`match`.  It can be called on the generated files:
 
     Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}")
 
-It tests filenames with `Lua` pattern matching and on matched items will
-execute command or function, specified in the second argument. For functions,
-two arguments are passed, first one is the current filename, the second one
-table with parameters. These parameters are the same as in previous section,
-except for `filename`, which contains generated output name.
+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.
+
+The above example will clean all output `HTML` files using the `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. 
+
+
 
 ### Filters
 
-Some default match actions which you can use are in the `filter` module.  It
-contains some functions which ares useful for fixing some `tex4ht` bugs or
-shortcomings.
+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.
 
 Example:
 
@@ -179,34 +324,35 @@ Example:
     Make:htlatex()
     Make:match("html$",process)
 
-
-Filter module is located in `make4ht-filter`. Function is returned, 
-which is used for building filter chains then. 
+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.
 
 Built-in filters are:
 
-cleanspan 
+cleanspan
 
 :    clean spurious span elements when accented characters are used
 
-cleanspan-nat 
+cleanspan-nat
 
 :    alternative clean span filter, provided by Nat Kuhn
 
-fixligatures 
+fixligatures
 
 :    decompose ligatures to base characters
 
-hruletohr 
+hruletohr
 
 :   `\hrule` commands are translated to series of underscore characters
     by `tex4ht`, this filter translate these underscores to `<hr>` elements
 
-entites 
+entites
 
 :    convert prohibited named entities to numeric entities (currently, only
      `&nbsp;`, as it causes validation errors, and `tex4ht` is producing it
-     sometimes
+     sometimes)
 
 fix-links
 
@@ -214,55 +360,239 @@ fix-links
      cross-reference commands may produce colons in internal links, which results in
      validation error.
 
-Function `filter` accepts also function arguments, in this case this function 
-takes file contents as parameter and modified contents are returned.
+mathjaxnode
+
+:    use [mathjax-node-page](https://github.com/pkra/mathjax-node-page/) to
+     convert from MathML code to HTML + CSS or SVG. See [the available
+     settings](#mathjaxsettings).
+
+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 filter  = require "make4ht-filter"
     local changea = function(s) return s:gsub("a","z") end
-    local process = filter{"cleanspan", "fixligatures", changea}            
-    Make:htlatex()                                                              
+    local process = filter{"cleanspan", "fixligatures", changea}
     Make:htlatex()
-    Make:match("html$",process) 
+    Make:htlatex()
+    Make:match("html$",process)
 
-In this case, spurious span elements are joined, ligatures are decomposed,
+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
+directly the XML object. This enables more powerful
+operations than the regex based filters from the previous section. 
+
+Example:
+
+    local domfilter = require "make4ht-domfilter"
+    local process = domfilter {"joincharacters"}
+    Make:match("html$", process)
+
+
+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.
+
+fixinlines
+
+:  put all inline elements which are direct children of the `<body>` elements to a paragraph.
+
+idcolons
+
+:  replace the colon (`:`) character in internal links and `id` attributes. They cause validation issues.
+
+joincharacters
+
+:  join consecutive `<span>` or `<mn>` elements.
+
+### 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:
+
+write\_job(parameters)
+
+:  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.
+
+execute(parameters)
+
+:  execute Aeneas.
+
+process\_files(parameters)
+
+:  process the audio and generated subtitle files.
+
+
+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.
+
+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 bellow. 
+
+text\_type 
+
+:  type of the input. The `aeneas` DOM filter produces `unparsed` text type.
+
+id\_sort 
+
+:  sorting of id attributes. Default value is `numeric`.
+
+id\_regex 
+
+:  regular expression to parse the id attributes.
+
+sub\_format 
+
+:  generated subtitle format. Default `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 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. 
+
+Example:
+
+    filter_settings "aeneas-config" {
+      map = {
+        ["sampleli1.html"] = {audio_file="sample.mp3"}, 
+        ["sample.html"] = false
+      }
+    }
+
+Table keys are the configured file names. It is necessary to insert them as
+`["filename.html"]`, because of Lua syntax rules.
+
+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 an
+corresponding audio file.
+
+The filenames of sub files corresponds to 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`.
+
+Available `map` options:
+
+
+audio\_file 
+
+:  the corresponding audio file 
+
+sub\_file 
+
+:  name of the generated subtitle file
+
+The following options are same as their counter-parts 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
+
+
+
+
 ## Image conversion
 
-It is possible to convert parts of LaTeX input to pictures, it is used 
+It is possible to convert parts of LaTeX input to pictures, it is used
 for example for math or diagrams in `tex4ht`. 
 
-These pictures are stored in special `dvi` file, on which `dvi to image` 
-commands are called. 
+These pictures are stored in a special `dvi` file, which can be processed by
+the `dvi to image` commands. 
 
-This conversion is normally configured in the `env file`, 
+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 `t4ht` application and conversion
+This configuration is processed by the `t4ht` application and conversion
 commands are called for all pictures.
 
-It is possible to disable `t4ht` image processing and configure image 
-conversion in the make file:
+It is possible to disable `t4ht` image processing and configure image
+conversion in the build file:
 
     Make:image("png$",
-    "dvipng -bg Transparent -T tight -o ${output}  -pp ${page} ${source}")                                                       
+    "dvipng -bg Transparent -T tight -o ${output}  -pp ${page} ${source}")
 
 
 `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 table with parameters as argument.
+Action can be either string template with conversion command,
+or function which takes a table with parameters as an argument.
 
 There are three parameters:
 
-  - output - output image file name
-  - source - `dvi` file with the pictures
-  - page   - page number of the converted image
+  - `output` - output image file name
+  - `source` - `dvi` file with the pictures
+  - `page`   - page number of the converted image
 
 ## The `mode` variable
 
-The `mode` variable contains contents of `--mode` command line option. 
-It can be used to run some commands conditionally. For example:
+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{} 
@@ -281,13 +611,163 @@ LaTeX is called only once when `make4ht` is called with `draft` mode:
 
 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`, you can use the following settings, based on `oolatex`
+the `OpenDocument Format (ODT)`, you can use the following settings, based on the `oolatex`
 command:
 
     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 "
 
+There are some functions to ease access to the settings:
+
+`set_settings{parameters}`
+
+:   overwrite settings with values from a passed table
+
+`settings_add{parameters}`
+
+:   add values to the current settings 
+
+`filter_settings "filter name" {parameters}`
+
+:   set settings for a filter
+
+`get_filter_settings(name)`
+
+:   get settings for a filter
+
+
+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 "
+    }
+
+Settings for filters and extensions can be set using `filter_settings`:
+
+    
+    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.
+
+These settings may be set using `filter_settings` function.
+
+### The `tidy` extension
+
+options
+
+:  command line options for the `tidy` command. Default value is `-m -utf8 -w 512 -q`.
+
+### 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.
+
+Example
+
+    filter_settings "fixinlines" {inline_elements = {a = true, b = true}}
+
+### The `joincharacters` dom filter
+
+charelements 
+
+:  table of elements which should be joined if several instances with the same value of `class` attribute are side by side.
+
+Example
+
+    filter_settings "joincharacters" { charclases = { span=true, mn = true}}
+
+### The `mathjaxnode` filter {#mathjaxsettings}
+
+options
+
+:  command line options for the `mjpage` command. Default value is `--output CommonHTML`
+
+Example
+
+    filter_settings "mathjaxnode" {
+      options="--output SVG --font Neo-Euler"
+    }
+
+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`
+
+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
+   sub-directory of the current directory. Only TeX font is supported at the moment.
+
+Example
+
+
+    filter_settings "mathjaxnode" {
+      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: `"([^%.^%?^!]*)([%.%?!]?)"`.
+
+# Configuration file {#configfile}
+
+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.
+
+## Location 
+
+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`).
+
+## Additional commands
+
+There are two additional commands:
+
+`Make:enable_extension(name)`
+
+:  require extension
+
+`Make:disable_extension(name)`
+
+:  disable extension
+
+## Example
+
+The following configuration add support for the `biber` command, requires
+`common_domfilters` extension and requires MathML
+output for math.
+
+    Make:add("biber", "biber ${input}")
+    Make:enable_extension "common_domfilters"
+    settings_add {
+      tex4ht_sty_par =",mathml"
+    }
 
 # Command line options
 
@@ -301,6 +781,7 @@ command:
     -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
@@ -311,16 +792,16 @@ command:
     <filename> (string) Input file name
 
 
-You can still use `make4ht` in same way as `htlatex`
+You can still invoke `make4ht` in the same way as `htlatex`:
 
-    make4ht filename "customcfg, charset=utf-8" " -cunihtf -utf8" " -dfoo"
+    make4ht filename "customcfg, charset=utf-8" "-cunihtf -utf8" "-dfoo"
 
-Note that this will not use `make4ht` routines for output dir making and
-copying If you want to use them, change the line above to:
+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:
 
-    make4ht filename "customcfg, charset=utf-8" " -cunihtf -utf8"  -d foo
+    make4ht -d foo filename "customcfg, charset=utf-8" "-cunihtf -utf8"
 
-This call has the same effect as following:
+This call has the same effect as the following:
 
     make4ht -u -c customcfg -d foo filename
 
@@ -332,4 +813,32 @@ Specified path can be relative to current directory, or absolute:
     make4ht -d ~/gotohomedir filename
     make4ht -d c:\documents\windowspathsareworkingtoo filename
 
+# Troubleshooting 
 
+## Incorrect handling of command line arguments for `tex4ht`, `t4ht` or `latex`
+
+Sometimes, you may get a similar error:
+
+    make4ht:unrecognized parameter: i
+
+It may be caused by a following `make4ht` invocation:
+
+    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:
+
+    make4ht -d foo hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8"
+
+Another option is to add a space before `tex4ht` options:
+
+    make4ht hello.tex "customcfg,charset=utf-8" " -cunihtf -utf8" -d foo
+
+The former way is preferable, though.
+
+# License
+
+Permission is granted to copy, distribute and/or modify this software
+under the terms of the LaTeX Project Public License, version 1.3.
diff --git a/Master/texmf-dist/doc/support/make4ht/changelog.tex b/Master/texmf-dist/doc/support/make4ht/changelog.tex
index 752787d1594..26614e59491 100644
--- a/Master/texmf-dist/doc/support/make4ht/changelog.tex
+++ b/Master/texmf-dist/doc/support/make4ht/changelog.tex
@@ -1,11 +1,253 @@
-\section{Changelog}\label{changelog}
+\hypertarget{changelog}{%
+\section{Changelog}\label{changelog}}
 
 \begin{itemize}
 \item
+  2018/04/09
+
+  \begin{itemize}
+  \tightlist
+  \item
+    released version \texttt{0.2}
+  \item
+    disabled default loading of \texttt{common\_domfilters} extension
+  \end{itemize}
+\item
+  2018/04/06
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added \texttt{Make:enable\_extension} and
+    \texttt{Make:disable\_extension} functions
+  \item
+    documented the configuration file
+  \end{itemize}
+\item
+  2018/03/09
+
+  \begin{itemize}
+  \tightlist
+  \item
+    load the configuration file before extensions
+  \end{itemize}
+\item
+  2018/03/02
+
+  \begin{itemize}
+  \tightlist
+  \item
+    Aeneas execution works
+  \item
+    Aeneas documentation
+  \item
+    added support for \texttt{.make4ht} configuration file
+  \end{itemize}
+\item
+  2018/02/28
+
+  \begin{itemize}
+  \tightlist
+  \item
+    Aeneas configuration file creation works
+  \end{itemize}
+\item
+  2018/02/22
+
+  \begin{itemize}
+  \tightlist
+  \item
+    fixed bug in \texttt{fixinlines} DOM filter
+  \end{itemize}
+\item
+  2018/02/21
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added Aeneas domfilter
+  \item
+    fixed bugs in \texttt{joincharacters} DOM filter
+  \end{itemize}
+\item
+  2018/02/20
+
+  \begin{itemize}
+  \tightlist
+  \item
+    fixed bug in \texttt{joincharacters} DOM filter
+  \item
+    make \texttt{woff} default font format for \texttt{mathjaxnode}
+  \item
+    added documentation for \texttt{mathjaxnode} settings
+  \end{itemize}
+\item
+  2018/02/19
+
+  \begin{itemize}
+  \tightlist
+  \item
+    fixed bug in filter loading
+  \item
+    added \texttt{mathjaxnode} extension
+  \end{itemize}
+\item
+  2018/02/15
+
+  \begin{itemize}
+  \tightlist
+  \item
+    use HTML5 as a default format
+  \item
+    use \texttt{common\_domfilters} implicitly for the XHTML and HTML5
+    formats
+  \end{itemize}
+\item
+  2018/02/12
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added \texttt{common\_domfilters} extension
+  \item
+    documented DOM filters
+  \end{itemize}
+\item
+  2018/02/12
+
+  \begin{itemize}
+  \tightlist
+  \item
+    handle XML parsing errors in the DOM handler
+  \item
+    enable extension loading in Formatters
+  \end{itemize}
+\item
+  2018/02/11
+
+  \begin{itemize}
+  \tightlist
+  \item
+    fixed Tidy extension output to support LuaXML
+  \item
+    fixed white space issues with \texttt{joincharacters} DOM filter
+  \end{itemize}
+\item
+  2018/02/09
+
+  \begin{itemize}
+  \tightlist
+  \item
+    fixed issues with the Mathjax filter
+  \item
+    documented basic info about thd DOM filters
+  \item
+    DOM filter optimalizations
+  \end{itemize}
+\item
+  2018/02/08
+
+  \begin{itemize}
+  \tightlist
+  \item
+    make Tidy extension configurable
+  \item
+    documented filter settings
+  \end{itemize}
+\item
+  2018/02/07
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added filter for Mathjax-node
+  \end{itemize}
+\item
+  2018/02/06
+
+  \begin{itemize}
+  \tightlist
+  \item
+    created DOM filter function
+  \item
+    added DOM filter for spurious inlinine elements
+  \end{itemize}
+\item
+  2018/02/03
+
+  \begin{itemize}
+  \tightlist
+  \item
+    added settings handling functions
+  \item
+    settings made available for extensions and filters
+  \end{itemize}
+\item
+  2017/12/08
+
+  \begin{itemize}
+  \tightlist
+  \item
+    fixed the \texttt{mk4} build file loading when it is placed in the
+    current working dir and another one with same filename somewhere in
+    the TEXMF tree.
+  \end{itemize}
+\item
+  2017/11/10
+
+  \begin{itemize}
+  \tightlist
+  \item
+    Added new filter: \texttt{svg-height}. It tries to fix height of
+    some of the images produced by \texttt{dvisvgm}
+  \end{itemize}
+\item
+  2017/10/06
+
+  \begin{itemize}
+  \tightlist
+  \item
+    Added support for output format selection. Supported formats are
+    \texttt{xhtml}, \texttt{html5} and \texttt{odt}
+  \item
+    Added support for extensions
+  \end{itemize}
+\item
+  2017/09/10
+
+  \begin{itemize}
+  \tightlist
+  \item
+    Added support for Latexmk
+  \item
+    Added support of \texttt{math} library and \texttt{tonumber}
+    function in the build files
+  \end{itemize}
+\item
+  2017/09/04
+
+  \begin{itemize}
+  \tightlist
+  \item
+    fixed bug caused by the previous change -- the --help and --version
+    didn't work
+  \end{itemize}
+\item
+  2017/08/22
+
+  \begin{itemize}
+  \tightlist
+  \item
+    fixed the command line option parsing for \texttt{tex4ht},
+    \texttt{t4ht} and \texttt{latex} commands
+  \item
+    various grammar and factual fixes in the documentation
+  \end{itemize}
+\item
   2017/04/26
 
   \begin{itemize}
-  \itemsep1pt\parskip0pt\parsep0pt
+  \tightlist
   \item
     Released version \texttt{v0.1c}
   \end{itemize}
@@ -13,15 +255,15 @@
   2017/03/16
 
   \begin{itemize}
-  \itemsep1pt\parskip0pt\parsep0pt
+  \tightlist
   \item
-    check for \texttt{TeX capacity exceeded} error in the \LaTeX~run.
+    check for \texttt{TeX\ capacity\ exceeded} error in the \LaTeX~run.
   \end{itemize}
 \item
   2016/12/19
 
   \begin{itemize}
-  \itemsep1pt\parskip0pt\parsep0pt
+  \tightlist
   \item
     use full input name in \texttt{tex\_file} variable. This should
     enable use of files without \texttt{.tex} extension.
@@ -30,7 +272,7 @@
   2016/10/22
 
   \begin{itemize}
-  \itemsep1pt\parskip0pt\parsep0pt
+  \tightlist
   \item
     new command available in the build file:
     \texttt{Make:add\_file(filename)}. This enables filters and commands
@@ -43,7 +285,7 @@
   2016/10/18
 
   \begin{itemize}
-  \itemsep1pt\parskip0pt\parsep0pt
+  \tightlist
   \item
     new filter: replace colons in \texttt{id} and \texttt{href}
     attributes with underscores
@@ -52,7 +294,7 @@
   2016/01/11
 
   \begin{itemize}
-  \itemsep1pt\parskip0pt\parsep0pt
+  \tightlist
   \item
     fixed bug in loading documents with full path specified
   \end{itemize}
@@ -60,18 +302,18 @@
   2015/12/06 version 0.1b
 
   \begin{itemize}
-  \itemsep1pt\parskip0pt\parsep0pt
+  \tightlist
   \item
-    modifed lapp library to recognize \texttt{-{}-version} and
+    modifed lapp library to recognize \texttt{-\/-version} and
   \item
-    added \texttt{-{}-help} and \texttt{-{}-version} command line
+    added \texttt{-\/-help} and \texttt{-\/-version} command line
     options
   \end{itemize}
 \item
   2015/11/30
 
   \begin{itemize}
-  \itemsep1pt\parskip0pt\parsep0pt
+  \tightlist
   \item
     use \texttt{kpse} library for build file locating
   \end{itemize}
@@ -79,7 +321,7 @@
   2015/11/17
 
   \begin{itemize}
-  \itemsep1pt\parskip0pt\parsep0pt
+  \tightlist
   \item
     better \texttt{-jobname} handling
   \end{itemize}
@@ -87,18 +329,18 @@
   2015/09/23 version 0.1a
 
   \begin{itemize}
-  \itemsep1pt\parskip0pt\parsep0pt
+  \tightlist
   \item
     various documentation updates
+  \item
+    \texttt{mozhtf} profile for unicode output is used, this should
+    prevent ligatures in the output files
   \end{itemize}
 \item
-  \texttt{mozhtf} profile for unicode output is used, this should
-  prevent ligatures in the output files
-\item
   2015/06/29 version 0.1
 
   \begin{itemize}
-  \itemsep1pt\parskip0pt\parsep0pt
+  \tightlist
   \item
     major README file update
   \end{itemize}
@@ -106,7 +348,7 @@
   2015/06/26
 
   \begin{itemize}
-  \itemsep1pt\parskip0pt\parsep0pt
+  \tightlist
   \item
     added Makefile
   \item
diff --git a/Master/texmf-dist/doc/support/make4ht/extensions/common_domfilters.lua b/Master/texmf-dist/doc/support/make4ht/extensions/common_domfilters.lua
new file mode 100644
index 00000000000..7c9a2dfaea4
--- /dev/null
+++ b/Master/texmf-dist/doc/support/make4ht/extensions/common_domfilters.lua
@@ -0,0 +1,27 @@
+local M = {}
+
+
+local filter = require "make4ht-domfilter"
+-- local process = filter {"fixinlines", "idcolons", "joincharacters" }
+
+-- filters support only html formats
+function M.test(format)
+  if format == "odt" then return false end
+  return true
+end
+
+function M.modify_build(make)
+  local process = filter {"fixinlines", "idcolons", "joincharacters"}
+  make:match("html$", process)
+  local matches = make.matches
+  -- the filters should be first match to be executed, especially if tidy
+  -- should be executed as well
+  if #matches > 1 then
+    local last = matches[#matches]
+    table.insert(matches, 1, last)
+    matches[#matches] = nil
+  end
+  return make
+end
+
+return M
diff --git a/Master/texmf-dist/doc/support/make4ht/extensions/common_filters.lua b/Master/texmf-dist/doc/support/make4ht/extensions/common_filters.lua
new file mode 100644
index 00000000000..513fbed34ee
--- /dev/null
+++ b/Master/texmf-dist/doc/support/make4ht/extensions/common_filters.lua
@@ -0,0 +1,26 @@
+local M = {}
+
+
+local filter = require "make4ht-filter"
+local process = filter {"cleanspan-nat", "fixligatures", "hruletohr", "entities", "fix-links"}
+
+-- filters support only html formats
+function M.test(format)
+  if format == "odt" then return false end
+  return true
+end
+
+function M.modify_build(make)
+  make:match("html$", process)
+  local matches = make.matches
+  -- the filters should be first match to be executed, especially if tidy
+  -- should be executed as well
+  if #matches > 1 then
+    local last = matches[#matches]
+    table.insert(matches, 1, last)
+    matches[#matches] = nil
+  end
+  return make
+end
+
+return M
diff --git a/Master/texmf-dist/doc/support/make4ht/extensions/latexmk.lua b/Master/texmf-dist/doc/support/make4ht/extensions/latexmk.lua
new file mode 100644
index 00000000000..bf4dcdde5a4
--- /dev/null
+++ b/Master/texmf-dist/doc/support/make4ht/extensions/latexmk.lua
@@ -0,0 +1,31 @@
+-- use Latexmk in first LaTeX call
+-- only in the first call, because we don't need to execute  biber, etc. in the subsequent
+-- LaTeX calls, these are only for resolving the cross-references
+local M = {}
+function M.modify_build(make)
+  local used = false
+  local first 
+  local build_seq = make.build_seq
+  -- find first htlatex call in the build sequence
+  for pos,v in ipairs(build_seq) do
+    if v.name == "htlatex" and not first then
+      first = pos
+    end
+  end
+  -- if htlatex was found
+  if first then
+    -- add dummy latexmk call to the build sequence
+    make:latexmk {}
+    -- replace name, command and type in the first htlatex
+    -- call with values from the dummy latexmk call
+    local replaced = build_seq[first]
+    local latexmk = build_seq[#build_seq]
+    replaced.name = latexmk.name
+    replaced.command = latexmk.command
+    replaced.type = latexmk.type
+    -- remove the dummy latexmk
+    table.remove(build_seq)
+  end
+  return make
+end
+return M
diff --git a/Master/texmf-dist/doc/support/make4ht/extensions/mathjaxnode.lua b/Master/texmf-dist/doc/support/make4ht/extensions/mathjaxnode.lua
new file mode 100644
index 00000000000..cbad897d4ec
--- /dev/null
+++ b/Master/texmf-dist/doc/support/make4ht/extensions/mathjaxnode.lua
@@ -0,0 +1,16 @@
+local M = {}
+
+
+local filter = require "make4ht-filter"
+function M.test(format)
+  if format == "odt" then return false end
+  return true
+end
+
+function M.modify_build(make)
+  local mathjax = filter { "mathjaxnode"}
+  make:match("html$",mathjax)
+  return make
+end
+
+return M
diff --git a/Master/texmf-dist/doc/support/make4ht/extensions/tidy.lua b/Master/texmf-dist/doc/support/make4ht/extensions/tidy.lua
new file mode 100644
index 00000000000..cf8ea9785a5
--- /dev/null
+++ b/Master/texmf-dist/doc/support/make4ht/extensions/tidy.lua
@@ -0,0 +1,57 @@
+local M = {}
+
+function M.test(format)
+  if format == "odt" then return false end
+  return true
+end
+
+local empty_elements = {
+  area=true,
+  base=true,
+  br=true,
+  col=true,
+  embed=true,
+  hr=true,
+  img=true,
+  input=true,
+  keygen=true,
+  link=true,
+  meta=true,
+  param=true,
+  source=true,
+  track=true,
+  wbr=true,
+}
+
+-- LuaXML cannot read HTML with unclosed tags (like <meta name="hello" content="world">)
+-- Tidy removes end slashes in the HTML output, so
+-- this function will add them back
+local function close_tags(s)
+  return s:gsub("<(%w+)([^>]-)>", function(tag, rest)
+    local endslash = ""
+    if empty_elements[tag] then endslash = " /" end
+    return string.format("<%s%s%s>", tag, rest, endslash)
+  end)
+end
+    
+
+
+function M.modify_build(make)
+  make:match("html$", function(filename, par)
+    local settings = get_filter_settings "tidy" or {}
+    par.options = par.options or settings.options or "-utf8 -w 512 -ashtml -q"
+    local command = "tidy ${options}  ${filename}" % par
+    print("execute: ".. command)
+    -- os.execute(command)
+    local run = io.popen(command, "r")
+    local result = run:read("*all")
+    run:close()
+    result = close_tags(result)
+    local f = io.open(filename, "w")
+    f:write(result)
+    f:close()
+  end)
+  return make
+end
+
+return M
diff --git a/Master/texmf-dist/doc/support/make4ht/formats/html5.lua b/Master/texmf-dist/doc/support/make4ht/formats/html5.lua
new file mode 100644
index 00000000000..633a45e7f34
--- /dev/null
+++ b/Master/texmf-dist/doc/support/make4ht/formats/html5.lua
@@ -0,0 +1,17 @@
+local M = {}
+
+local mkutils = require "mkutils"
+
+function M.prepare_extensions(extensions)
+  -- return mkutils.add_extensions("+common_domfilters", extensions)
+  return extensions --mkutils.add_extensions("+tidy", extensions)
+end
+
+function M.prepare_parameters(parameters,extensions)
+  parameters.tex4ht_sty_par  = parameters.tex4ht_sty_par .. ",html5"
+  parameters = mkutils.extensions_prepare_parameters(extensions,parameters)
+  return parameters
+end
+
+
+return M
diff --git a/Master/texmf-dist/doc/support/make4ht/formats/odt.lua b/Master/texmf-dist/doc/support/make4ht/formats/odt.lua
new file mode 100644
index 00000000000..66105166f32
--- /dev/null
+++ b/Master/texmf-dist/doc/support/make4ht/formats/odt.lua
@@ -0,0 +1,11 @@
+local M = {}
+local mkutils = require "mkutils"
+
+function M.prepare_parameters(settings, extensions)
+  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 "
+  settings = mkutils.extensions_prepare_parameters(extensions, settings)
+  return settings
+end
+return M
diff --git a/Master/texmf-dist/doc/support/make4ht/formats/xhtml.lua b/Master/texmf-dist/doc/support/make4ht/formats/xhtml.lua
new file mode 100644
index 00000000000..4a4ac6689ca
--- /dev/null
+++ b/Master/texmf-dist/doc/support/make4ht/formats/xhtml.lua
@@ -0,0 +1,16 @@
+local M = {}
+
+local mkutils = require "mkutils"
+
+function M.prepare_extensions(extensions)
+  -- return mkutils.add_extensions("+common_domfilters", extensions)
+  return extensions
+end
+
+function M.prepare_parameters(parameters,extensions)
+  parameters = mkutils.extensions_prepare_parameters(extensions,parameters)
+  return parameters
+end
+
+
+return M
diff --git a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.pdf
index 2867bf29dc0..fa9039865ce 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 973a349c6ce..6815e50606f 100644
--- a/Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex
+++ b/Master/texmf-dist/doc/support/make4ht/make4ht-doc.tex
@@ -9,6 +9,7 @@
 \else
 \usepackage{fontspec}
 \setmainfont{TeX Gyre Schola}
+\setmonofont[Scale=MatchLowercase]{Inconsolatazi4}
 \fi
 \usepackage{microtype}
 \providecommand\tightlist{\relax}
diff --git a/Master/texmf-dist/doc/support/make4ht/readme.tex b/Master/texmf-dist/doc/support/make4ht/readme.tex
index 77e1ecdc6b1..df67a151b87 100644
--- a/Master/texmf-dist/doc/support/make4ht/readme.tex
+++ b/Master/texmf-dist/doc/support/make4ht/readme.tex
@@ -1,68 +1,186 @@
-\section{Introduction}\label{introduction}
+\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. The \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 simple build system for tex4ht. It is both
-executable which simplifies \texttt{tex4ht} execution and a library
-which can be used to create customized conversion programs. An example
-of such conversion program is
-\href{https://github.com/michal-h21/tex4ebook}{tex4ebook}
+\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}
 
-\subsection{License}\label{license}
+The options for various parts of the system can be passed on the command
+line:
 
-Permission is granted to copy, distribute and/or modify this software
-under the terms of the LaTeX Project Public License, version 1.3.
+\begin{verbatim}
+htlatex filename "tex4ht.sty options" "tex4ht_options" "t4ht_options" "latex_options"
+\end{verbatim}
 
-\subsection{How it works}\label{how-it-works}
+For basic \texttt{HTML} conversion it is possible to use the most basic
+invocation:
 
-Default compilation script for \texttt{tex4ht}, named \texttt{htlatex}
-compiles LaTeX files to \texttt{HTML} with this command sequence:
+\begin{verbatim}
+htlatex filename.tex
+\end{verbatim}
+
+It can be much more involved for \texttt{HTML\ 5} output in
+\texttt{UTF-8} encoding:
 
 \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 options filename
-t4ht options filename
-\end{verbatim}
-
-The problem is that this is inefficient when you need to run program
-which interact with LaTeX, such as \texttt{Makeindex} or
-\texttt{Bibtex}. In that case, you need to create new script based on
-the default one, or run \texttt{htlatex} twice, which means six LaTeX
-runs.
-
-Another problem is with \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 some
-subdirectory, they will be copied to the output directory, but links
-will be pointing to non existing subdirectory.
-
-Image conversion is directed with the
+htlatex filename.tex "xhtml,html5,charset=utf-8" "-cmozhtf -utf8"
+\end{verbatim}
+
+\texttt{make4ht} can simplify it:
+
+\begin{verbatim}
+make4ht -uf html5 filename.tex
+\end{verbatim}
+
+Another issue is the fixed compilation order and 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 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:
+
+\begin{verbatim}
+make4ht -um draft -f html5 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.
+
+\begin{verbatim}
+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}, with really strange syntax based on whitespace and
+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}. With \texttt{make4ht} build files, we have simple mean to
-fix these issues. We can change image conversion parameters without need
-to modify the \texttt{env file}, and call actions on the output files.
+dependent}. \texttt{make4ht} provides simpler means for the image
+conversion in the build files.
+
+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.
+processors or \texttt{HTML\ tidy} or \texttt{Lua} functions.
 
 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 build script are written.
+in which the build scripts are written.
+
+\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.
+Supported formats are:
+
+\begin{itemize}
+\tightlist
+\item
+  \texttt{xhtml}
+\item
+  \texttt{html5}
+\item
+  \texttt{odt}
+\end{itemize}
+
+The \texttt{-\/-format} option can be also used for extension loading.
+
+\hypertarget{extensions}{%
+\subsection{Extensions}\label{extensions}}
 
-\section{Build files}\label{build-files}
+Extensions can be used to modify the build process without the need to
+use a build file. They may post-process the output files or request
+additional commands for the compilation.
 
-\subsection{Commands}\label{commands}
+The extensions can be enabled or disabled by appending
+\texttt{+EXTENSION} or \texttt{-EXTENSION} after the output format name:
 
-By default, build file is saved in file named
-\texttt{filename + .mk4 extension}. You can choose different build file
-with \texttt{-e} or \texttt{-{}-build-file} command line option.
+\begin{verbatim}
+ make4ht -uf html5+tidy filename.tex
+\end{verbatim}
+
+Available extensions:
+
+\begin{description}
+\item[latexmk]
+use \texttt{Latexmk} for \LaTeX~compilation.
+\item[tidy]
+clean the \texttt{HTML} files using the \texttt{tidy} command.
+\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}.
+\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}.
+\end{description}
+
+\hypertarget{build-files}{%
+\section{Build files}\label{build-files}}
 
-Sample:
+\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
+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.
+
+Sample build file:
 
 \begin{verbatim}
 Make:htlatex()
@@ -70,107 +188,166 @@ 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, \texttt{tidy} command is executed on the
-output \texttt{html} file.
+\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.
 
 Note that you don't have to call \texttt{tex4ht} and \texttt{t4ht}
 commands explicitly in the build file, they are called automatically.
 
-You can add more commands like \texttt{Make:htlatex} with
+\hypertarget{user-commands}{%
+\subsection{User commands}\label{user-commands}}
+
+You can add more commands like \texttt{Make:htlatex} using
+\texttt{Make:add} command:
 
 \begin{verbatim}
 Make:add("name", "command", {parameters}, repetition)
 \end{verbatim}
 
-it can be called with
+The \texttt{name} and \texttt{command} parameters are required, rest of
+the parameters are optional.
 
-\begin{verbatim}
-Make:name()
-\end{verbatim}
+This defines \texttt{name} command, which can be then executed as
+\texttt{Make:name()} command.
 
-\texttt{command} can be text template, or function:
+\hypertarget{provided-commands}{%
+\subsubsection{Provided commands}\label{provided-commands}}
+
+\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}
+
+\hypertarget{command-function}{%
+\subsubsection{Command function}\label{command-function}}
+
+The \texttt{command} parameter can be either string template or
+function:
 
 \begin{verbatim}
-Make:add("text", "hello, input file: ${input}")
+Make:add("text", "echo hello, input file: ${input}")
 Make:add("function", function(params) 
   for k, v in pairs(params) do 
     print(k..": "..v) 
-  end
+  end, {custom="Hello world"}
 )
 \end{verbatim}
 
-\texttt{parameters} is a table or \texttt{nil} value.
+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}}
 
-Default parameters are:
+\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.
+
+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 default parameters are following:
 
 \begin{description}
-\item[htlatex]
+\item[\texttt{htlatex}]
 used compiler
-\item[input]
+\item[\texttt{input}]
 it is output file name in fact
-\item[tex\_file]
+\item[\texttt{tex\_file}]
 input TeX file
-\item[latex\_par]
+\item[\texttt{latex\_par}]
 parameters to \texttt{latex}
-\item[packages]
-insert additionl LaTeX code which is inserted before
+\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[tex4ht\_sty\_par]
+\item[\texttt{tex4ht\_sty\_par}]
 parameters to \texttt{tex4ht.sty}
-\item[tex4ht\_par]
-parameters to \texttt{tex4ht} application
-\item[t4ht\_par]
-parameters to \texttt{t4ht} application
-\item[outdir]
-output directory
-\item[repetition]
+\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[correct\_exit]
-expected \texttt{exit code} from the command. The compilation will be
-terminted when the command \texttt{exit code} is different.
+\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}
 
-You may add your own parameters, they will be accessible in templates
-and functions.
+\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.
 
-With \texttt{repetition}, you can limit number of command executions.
-Its value should be number or \texttt{nil}. This is used in the case of
-\texttt{tex4ht} and \texttt{t4ht} commands, as they should be executed
-only once and they would be executed multiple times if you include them
-in the build file, because they would be called also by
-\texttt{make4ht}. With \texttt{repetition}, second execution is blocked.
+\hypertarget{expected-exit-code}{%
+\subsubsection{Expected exit code}\label{expected-exit-code}}
 
-You can set expected exit code from a command with
-\texttt{correct\_exit}. Compilation is stopped when command returns
-different exit code. The situation is different 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.
+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.
 
-\subsection{File matches}\label{file-matches}
+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}
+function can be used in the build file to detect compilation errors in
+the TeX log file.
 
-Other type of action which can be specified in the build file are
-matches which may be called on the generated files:
+\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:
 
 \begin{verbatim}
 Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}")
 \end{verbatim}
 
-It tests filenames with \texttt{Lua} pattern matching and on matched
-items will execute command or function, specified in the second
-argument. For functions, two arguments are passed, first one is the
-current filename, the second one table with parameters. These parameters
-are the same as in previous section, except for \texttt{filename}, which
-contains generated output name.
+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.
 
-\subsubsection{Filters}\label{filters}
+If function is used instead, it will get two parameters. The first one
+is a current filename, the second one table with parameters.
 
-Some default match actions which you can use are in the \texttt{filter}
-module. It contains some functions which ares useful for fixing some
-\texttt{tex4ht} bugs or shortcomings.
+\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.
 
 Example:
 
@@ -182,8 +359,10 @@ Make:htlatex()
 Make:match("html$",process)
 \end{verbatim}
 
-Filter module is located in \texttt{make4ht-filter}. Function is
-returned, which is used for building filter chains then.
+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.
 
 Built-in filters are:
 
@@ -201,73 +380,260 @@ 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
+producing it sometimes)
 \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.
+\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[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 parameter and modified contents are
-returned.
+this function takes file contents as a parameter and modified contents
+are returned.
 
 Example:
 
 \begin{verbatim}
-local filter  = require "make4ht-filter"                                    
+local filter  = require "make4ht-filter"
 local changea = function(s) return s:gsub("a","z") end
-local process = filter{"cleanspan", "fixligatures", changea}            
-Make:htlatex()                                                              
+local process = filter{"cleanspan", "fixligatures", changea}
+Make:htlatex()
 Make:htlatex()
-Make:match("html$",process) 
+Make:match("html$",process)
 \end{verbatim}
 
-In this case, spurious span elements are joined, ligatures are
+In this example, spurious span elements are joined, ligatures are
 decomposed, and then all letters `a' are replaced with `z' letters.
 
-\subsection{Image conversion}\label{image-conversion}
+\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.
+
+Example:
+
+\begin{verbatim}
+local domfilter = require "make4ht-domfilter"
+local process = domfilter {"joincharacters"}
+Make:match("html$", process)
+\end{verbatim}
+
+Available DOM filters:
+
+\begin{description}
+\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.
+\item[fixinlines]
+put all inline elements which are direct children of the
+\texttt{\textless{}body\textgreater{}} elements to a paragraph.
+\item[idcolons]
+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.
+\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 an corresponding audio file.
+
+The filenames of sub files corresponds to 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}.
 
-These pictures are stored in special \texttt{dvi} file, on which
-\texttt{dvi to image} commands are called.
+These pictures are stored in a special \texttt{dvi} file, which can be
+processed by the \texttt{dvi\ to\ image} commands.
 
-This conversion is normally configured in the \texttt{env file}, which
+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 \texttt{t4ht} application and conversion
-commands are called for all pictures.
+configuration is processed by the \texttt{t4ht} application and
+conversion commands are called for all pictures.
 
 It is possible to disable \texttt{t4ht} image processing and configure
-image conversion in the make file:
+image conversion in the build file:
 
 \begin{verbatim}
 Make:image("png$",
-"dvipng -bg Transparent -T tight -o ${output}  -pp ${page} ${source}")                                                       
+"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 table with parameters as argument.
+command, or function which takes a table with parameters as an argument.
 
 There are three parameters:
 
 \begin{itemize}
-\itemsep1pt\parskip0pt\parsep0pt
+\tightlist
 \item
-  output - output image file name
+  \texttt{output} - output image file name
 \item
-  source - \texttt{dvi} file with the pictures
+  \texttt{source} - \texttt{dvi} file with the pictures
 \item
-  page - page number of the converted image
+  \texttt{page} - page number of the converted image
 \end{itemize}
 
-\subsection{The \texttt{mode} variable}\label{the-mode-variable}
+\hypertarget{the-mode-variable}{%
+\subsection{\texorpdfstring{The \texttt{mode}
+variable}{The mode variable}}\label{the-mode-variable}}
 
-The \texttt{mode} variable contains contents of \texttt{-{}-mode}
-command line option. It can be used to run some commands conditionally.
-For example:
+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:
 
 \begin{verbatim}
  if mode == "draft" then
@@ -287,12 +653,14 @@ called with \texttt{draft} mode:
 make4ht -m draft filename
 \end{verbatim}
 
-\subsection{The \texttt{settings} table}\label{the-settings-table}
+\hypertarget{the-settings-table}{%
+\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}, you can use the
-following settings, based on \texttt{oolatex} command:
+convert your file to the \texttt{OpenDocument\ Format\ (ODT)}, you can
+use the following settings, based on the \texttt{oolatex} command:
 
 \begin{verbatim}
 settings.tex4ht_sty_par = settings.tex4ht_sty_par ..",ooffice"
@@ -300,7 +668,196 @@ settings.tex4ht_par = settings.tex4ht_par .. " ooffice/! -cmozhtf"
 settings.t4ht_par = settings.t4ht_par .. " -cooxtpipes -coo "
 \end{verbatim}
 
-\section{Command line options}\label{command-line-options}
+There are some functions to ease access to the settings:
+
+\begin{description}
+\item[\texttt{set\_settings\{parameters\}}]
+overwrite settings with values from a passed table
+\item[\texttt{settings\_add\{parameters\}}]
+add values to the current settings
+\item[\texttt{filter\_settings\ "filter\ name"\ \{parameters\}}]
+set settings for a filter
+\item[\texttt{get\_filter\_settings(name)}]
+get settings for a filter
+\end{description}
+
+Using these functions, it is possible to simplify the settings for the
+\texttt{ODT} format:
+
+\begin{verbatim}
+settings_add {
+  tex4ht_sty_par =",ooffice",
+  tex4ht_par = " ooffice/! -cmozhtf",
+  t4ht_par = " -cooxtpipes -coo "
+}
+\end{verbatim}
+
+Settings for filters and extensions can be set using
+\texttt{filter\_settings}:
+
+\begin{verbatim}
+filter_settings "test" {
+  hello = "world"
+}
+\end{verbatim}
+
+These settings can be read in the extensions and filters using
+\texttt{get\_filter\_settings}:
+
+\begin{verbatim}
+function test(input)
+   local options = get_filter_settings("test")
+   print(options.hello)
+   return input
+end
+   
+\end{verbatim}
+
+\hypertarget{list-of-available-settings-for-filters-and-extensions.}{%
+\subsection{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.
+
+\hypertarget{the-tidy-extension}{%
+\subsubsection{\texorpdfstring{The \texttt{tidy}
+extension}{The tidy extension}}\label{the-tidy-extension}}
+
+\begin{description}
+\item[options]
+command line options for the \texttt{tidy} command. Default value is
+\texttt{-m\ -utf8\ -w\ 512\ -q}.
+\end{description}
+
+\hypertarget{the-fixinlines-dom-filter}{%
+\subsubsection{\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
+\texttt{body} element. The element names should be table keys, the
+values should be true.
+\end{description}
+
+Example
+
+\begin{verbatim}
+filter_settings "fixinlines" {inline_elements = {a = true, b = true}}
+\end{verbatim}
+
+\hypertarget{the-joincharacters-dom-filter}{%
+\subsubsection{\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.
+\end{description}
+
+Example
+
+\begin{verbatim}
+filter_settings "joincharacters" { charclases = { span=true, mn = true}}
+\end{verbatim}
+
+\hypertarget{mathjaxsettings}{%
+\subsubsection{\texorpdfstring{The \texttt{mathjaxnode}
+filter}{The mathjaxnode filter}}\label{mathjaxsettings}}
+
+\begin{description}
+\item[options]
+command line options for the \texttt{mjpage} command. Default value is
+\texttt{-\/-output\ CommonHTML}
+\end{description}
+
+Example
+
+\begin{verbatim}
+filter_settings "mathjaxnode" {
+  options="--output SVG --font Neo-Euler"
+}
+\end{verbatim}
+
+\begin{description}
+\item[cssfilename]
+\texttt{mjpage} 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 should be sub-directory of the current directory. Only TeX
+font is supported at the moment.
+\end{description}
+
+Example
+
+\begin{verbatim}
+filter_settings "mathjaxnode" {
+  fontdir="fonts/TeX/woff/" 
+}
+\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{configfile}{%
+\section{Configuration file}\label{configfile}}
+
+It is possible to globally modify the build settings using the
+configuration file. New compilation commands can be added, extensions
+can be loaded or disabled and settings can be set.
+
+\hypertarget{location}{%
+\subsection{Location}\label{location}}
+
+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}).
+
+\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 configuration add 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{command-line-options}{%
+\section{Command line options}\label{command-line-options}}
 
 \begin{verbatim}
 make4ht - build system for tex4ht
@@ -313,6 +870,7 @@ make4ht [options] filename ["tex4ht.sty op." "tex4ht op."
 -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
@@ -323,20 +881,22 @@ make4ht [options] filename ["tex4ht.sty op." "tex4ht op."
 <filename> (string) Input file name
 \end{verbatim}
 
-You can still use \texttt{make4ht} in same way as \texttt{htlatex}
+You can still invoke \texttt{make4ht} in the same way as
+\texttt{htlatex}:
 
 \begin{verbatim}
-make4ht filename "customcfg, charset=utf-8" " -cunihtf -utf8" " -dfoo"
+make4ht filename "customcfg, charset=utf-8" "-cunihtf -utf8" "-dfoo"
 \end{verbatim}
 
-Note that this will not use \texttt{make4ht} routines for output dir
-making and copying If you want to use them, change the line above to:
+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{verbatim}
-make4ht filename "customcfg, charset=utf-8" " -cunihtf -utf8"  -d foo
+make4ht -d foo filename "customcfg, charset=utf-8" "-cunihtf -utf8"
 \end{verbatim}
 
-This call has the same effect as following:
+This call has the same effect as the following:
 
 \begin{verbatim}
 make4ht -u -c customcfg -d foo filename
@@ -352,3 +912,47 @@ make4ht -d ../gotoparrentdir filename
 make4ht -d ~/gotohomedir filename
 make4ht -d c:\documents\windowspathsareworkingtoo filename
 \end{verbatim}
+
+\hypertarget{troubleshooting}{%
+\section{Troubleshooting}\label{troubleshooting}}
+
+\hypertarget{incorrect-handling-of-command-line-arguments-for-tex4ht-t4ht-or-latex}{%
+\subsection{\texorpdfstring{Incorrect handling of command line arguments
+for \texttt{tex4ht}, \texttt{t4ht} or
+\texttt{latex}}{Incorrect handling of command line arguments for tex4ht, t4ht or latex}}\label{incorrect-handling-of-command-line-arguments-for-tex4ht-t4ht-or-latex}}
+
+Sometimes, you may get a similar error:
+
+\begin{verbatim}
+make4ht:unrecognized parameter: i
+\end{verbatim}
+
+It may be caused by a following \texttt{make4ht} invocation:
+
+\begin{verbatim}
+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:
+
+\begin{verbatim}
+make4ht -d foo hello.tex "customcfg,charset=utf-8" "-cunihtf -utf8"
+\end{verbatim}
+
+Another option is to add a space before \texttt{tex4ht} options:
+
+\begin{verbatim}
+make4ht hello.tex "customcfg,charset=utf-8" " -cunihtf -utf8" -d foo
+\end{verbatim}
+
+The former way is preferable, though.
+
+\hypertarget{license}{%
+\section{License}\label{license}}
+
+Permission is granted to copy, distribute and/or modify this software
+under the terms of the LaTeX Project Public License, version 1.3.