summaryrefslogtreecommitdiff
path: root/support/make4ht/README
diff options
context:
space:
mode:
Diffstat (limited to 'support/make4ht/README')
-rw-r--r--support/make4ht/README1168
1 files changed, 715 insertions, 453 deletions
diff --git a/support/make4ht/README b/support/make4ht/README
index a99a108d69..df14833239 100644
--- a/support/make4ht/README
+++ b/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