Chapter 4
Calling Commands

We provide a build script, called make4ht, which simplifies the process. There is also a variant of make4ht, tex4ebook for e-book production. See the chapter Output Formats for more information on output formats.

4.1 make4ht Build System

The conversion command loads a script which takes on itself to invoke the different steps of the process, without user intervention. The command assumes the form:

make4ht [make4ht options] filename.tex "options1" "option2" "options3" "options4"

The first set of options is for the tex4ht.sty and *.4ht style files, the second set is for the tex4ht post-processor, the third for the t4ht post-processor, and the last one is for the LaTeX compiler.

These options are optional.

The basic invokation of make4ht looks like this:

make4ht filename.tex

This command requests a translation according to the default conditions, which are set to produce HTML 5 document.

make4ht filename.tex "2,info"

This command specifies some options for tex4ht.sty. The “2” option requests a break up of the output into separate web pages, in accordance to the two top sectioning levels of the document.

The info option requests inclusion of documentation of basic configurations to the filename.log file. You can open this file using a text editor to read this information.

Information about additional options can be found in the List of options section.

make4ht -c foo.cfg filename "frames" "" "-p"

This command requests LaTeX to load a Private Configuration Files, named foo.cfg, using the -c make4ht option. The frames option requires placing of the content and table of contents in separate frames. In addition, it asks the t4ht command not to produce bitmaps for pictures using the -p option.

4.2 make4ht Switches and Options

make4ht accepts following command line switches and options:

-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 nil)  Output directory 
-e,--build-file (default nil)  If build file is different than `filename`.mk4 
-f,--format  (default html5)  Output file format 
-h,--help  Display this message 
-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 the tex4ht command 
-s,--shell-escape Enables running external programs from LaTeX 
-v,--version  Display version number 
-x,--xetex Use xelatex for document compilation

You can either use the long form --mode, or the short form -m. Short options can be chained:

$ make4ht -lsm draft filename.tex

The above command is equvalent to the following that uses the long names:

$ make4ht --lua --shell-escape --mode draft filename.tex

Some of these options are discussed in other chapters, see section Private Configuration Files for details on configuration files requested using the -c option, and section Make4ht Build Files for details on build files requested using the -e option.

Supported output formats are described in the chapter Output Formats. They can be requested using the -f option. This option also supports extensions. This feature has been shown in the section Basic Usage of the tutorial.

4.2.1 TeX engine

make4ht uses TeX compiler to produce a DVI file. Normally, it uses PDFTeX engine, but you can also select LuaTeX or XeTeX, using the -l or -x switches.

The selected engine is important especially for handling of accented and non-Latin characters. While TeX4ht doesn’t support OpenType fonts, it can emulate the Fontspec package, so it supports documents that use it. With LuaTeX backend, TeX4ht should support all Unicode characters. With XeTeX, it needs special instructions to load non-Latin character support. See Unicode section for more details.

4.2.2 Terminal Output

make4ht hides the terminal output by default. It shows only errors and warnings. It doesn’t always show the correct error context. In such cases, try the -a debug option. It is also recommended to use output of this option for TeX4ht bug reports.

$ make4ht -a debug -m draft buggy.tex

4.2.3 Output Directory

To copy generated files to a different directoy, use the -d path option. The passed path can be absolute or relative to the current directory. It also doesn’t need to exist, make4ht will create it if necessary.

$ make4ht -d outdir filename.tex

Note that this option doesn’t remove any files from the current directory. If you want to remove the temporary files, use the -m clean option:

$ make4ht -m clean filename.tex

4.2.4 make4ht extensions

make4ht extensions can modify the build process – usually, they are used to post-process the generated files, to fix some issues that are hard to fix on the TeX level.

The extensions can be enabled or disabled by appending +EXTENSION or -EXTENSION after the output format name:

$ make4ht -uf html5+tidy filename.tex

Some of the available extensions:

detect_engine

choose TeX engine and format necessary for the document compilation from the magic comments in the document.

preprocess_input

add support for Rmarkdown, RTeX, and similar formats supported by Knith or Pandoc.

staticsite

generate files suitable for static site generators, such as Jekyll or Hugo.

You can find full a list of extensions in make4ht documentation.

4.3 Overview of the Translation Process

The translation of a LaTeX source file into HTML involves loading of the tex4ht.sty package. It watches loaded packages, and loads corresponding configuration files, named as <pkgname>.4ht. These configuration files patches commands provided by the packages, and insert special hooks, which are later filled with XML code for the output format.

To ensure that all packages are processed, tex4ht.sty needs to be loaded early, ideally before ∖documentclass.

Result of the LaTeX run is a DVI file that contain document text and special instructions with XML code, or with requests for pictures. This file is then processed by the tex4ht command. It generates the output XML or HTML files and the IDV file, which is then used for pictures.

The last command is t4ht. It generates pictures and CSS file.

Basic sequence of execution of these command is following:

latex      x            (or tex x) 
latex      x 
latex      x 
tex4ht     x 
t4ht       x

The three compilations with La(TeX) are needed to ensure proper links. The approach is illustrated in the picture 4.1.

x.tex

This is a source TeX/LaTeX/OtherTeX file that imports the style files tex4ht.sty and *.4ht. The style files define the features for the output.

tex4ht

The output of TeX is a standard dvi file interleaved with special instructions for the postprocessor tex4ht to use. The special instructions come from implicit and explicit requests made in the source file through commands of TeX4ht.

The utility tex4ht translates the dvi code into standard text, while obeying the requests it gets from the special instructions. The special instructions may request the creation of files, insertion of html code, filtering of pictures, and so forth.

In the extreme case that the source code contains no commands of TeX4ht, it gets the pure dvi code and it outputs (almost) plain text with no hypertext elements in it.

The special (\special) instructions seeded in the DVI code are not understood by dvi processors other than those of TeX4ht.

x.idv

This is a dvi file extracted from x.dvi, and it contains the pictures needed in the html files.

x.lg

This is a log file listing the pictures of x.idv, the png files that should be created, CSS information, and user directives introduced through the \Needs{...} command.

t4ht

This is an interpreter for executing the requests made in the x.lg script.