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