path: root/Master/texmf-dist/doc/support/make4ht/readme.tex

\section{Introduction}\label{introduction}

\texttt{make4ht} is a simple build system for tex4ht. It is both
executable which simplifies \texttt{tex4ht} execution and a library
which can be used to create customized conversion programs. An example
of such conversion program is
\href{https://github.com/michal-h21/tex4ebook}{tex4ebook}

\subsection{License}\label{license}

Permission is granted to copy, distribute and/or modify this software
under the terms of the LaTeX Project Public License, version 1.3.

\subsection{How it works}\label{how-it-works}

Default compilation script for \texttt{tex4ht}, named \texttt{htlatex}
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 options filename
t4ht options filename
\end{verbatim}

The problem is that this is inefficient when you need to run program
which interact with LaTeX, such as \texttt{Makeindex} or
\texttt{Bibtex}. In that case, you need to create new script based on
the default one, or run \texttt{htlatex} twice, which means six LaTeX
runs.

Another problem is with \texttt{t4ht} application. It reads file
\texttt{filename.lg}, generated by \texttt{tex4ht}, where are
instructions about generated files, \texttt{CSS} instructions, calls to
external applications, instructions for image conversions etc. It can be
instructed to copy generated files to some output directory, but it
doesn't preserve directory structure, so when you have images in some
subdirectory, they will be copied to the output directory, but links
will be pointing to non existing subdirectory.

Image conversion is directed with the
\href{http://www.tug.org/applications/tex4ht/mn35.html\#index35-73001}{env
file}, with really strange syntax based on whitespace and
\href{http://www.tug.org/applications/tex4ht/mn-unix.html\#index27-69005}{os
dependent}. With \texttt{make4ht} build files, we have simple mean to
fix these issues. We can change image conversion parameters without need
to modify the \texttt{env file}, and call actions on the output files.
These actions can be either external programs such as \texttt{xslt}
processors or \texttt{HTML tidy} or \texttt{Lua} functions.

The idea is to make system controlled by a build file. Because
\texttt{Lua} interpreter is included in modern TeX distributions and
\texttt{Lua} is ideal language for such task, it was chosen as language
in which build script are written.

\section{Build files}\label{build-files}

\subsection{Commands}\label{commands}

By default, build file is saved in file named
\texttt{filename + .mk4 extension}. You can choose different build file
with \texttt{-e} or \texttt{-{}-build-file} command line option.

Sample:

\begin{verbatim}
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, \texttt{tidy} command is executed on the
output \texttt{html} file.

Note that you don't have to call \texttt{tex4ht} and \texttt{t4ht}
commands explicitly in the build file, they are called automatically.

You can add more commands like \texttt{Make:htlatex} with

\begin{verbatim}
Make:add("name", "command", {parameters}, repetition)
\end{verbatim}

it can be called with

\begin{verbatim}
Make:name()
\end{verbatim}

\texttt{command} can be text template, or function:

\begin{verbatim}
Make:add("text", "hello, input file: ${input}")
Make:add("function", function(params) for k, v in pairs(params) do print(k..": "..v) end)
\end{verbatim}

\texttt{parameters} is a table or \texttt{nil} value.

Default parameters are:

\begin{description}
\item[htlatex]
used compiler
\item[input]
input file
\item[latex\_par]
parameters to \texttt{latex}
\item[tex4ht\_sty\_par]
parameters to \texttt{tex4ht.sty}
\item[tex4ht\_par]
parameters to \texttt{tex4ht} application
\item[t4ht\_par]
parameters to \texttt{t4ht} application
\item[outdir]
output directory
\item[repetition]
limit number of command execution.
\item[correct\_exit]
expected \texttt{exit code} from the command.
\end{description}

You may add your own parameters, they will be accessible in templates
and functions.

With \texttt{repetition}, you can limit number of command executions.
Its value should be number or \texttt{nil}. This is used in the case of
\texttt{tex4ht} and \texttt{t4ht} commands, as they should be executed
only once and they would be executed multiple times if you include them
in the build file, because they would be called also by
\texttt{make4ht}. With \texttt{repetition}, second execution is blocked.

You can set expected exit code from a command with
\texttt{correct\_exit}. Compilation is stopped when command returns
different exit code. Situation is little bit difficult with LaTeX (all
engines and formats in fact), because it doesn't differentiate between
fatal and non fatal errors and returns 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.

\subsection{File matches}\label{file-matches}

Other type of action which can be specified in the build file are
matches which may be called on the generated files:

\begin{verbatim}
Make:match("html$", "tidy -m -xml -utf8 -q -i ${filename}")
\end{verbatim}

It tests filenames with \texttt{Lua} pattern matching and on matched
items will execute command or function, specified in the second
argument. Parameters are the same as in previous section, except
\texttt{filename}, which contains generated output name.

\subsubsection{Filters}\label{filters}

Some default match actions which you can use are in the \texttt{filter}
module. It contains some functions which ares useful for fixing some
\texttt{tex4ht} bugs or shortcomings.

Example:

\begin{verbatim}
local filter = require "make4ht-filter"
local process = filter{"cleanspan", "fixligatures", "hruletohr"}
Make:htlatex()
Make:htlatex()
Make:match("html$",process)
\end{verbatim}

Filter module is located in \texttt{make4ht-filter}. Function is
returned, which is used for building filter chains then.

Built-in filters are:

\begin{description}
\item[cleanspan]
clean spurious span elements when accented characters are used
\item[cleanspan-nat]
alternative clean span filter, provided by Nat Kuhn
\item[fixligatures]
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
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
\end{description}

Function \texttt{filter} accepts also function arguments, in this case
this function takes file contents as 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 case, spurious span elements are joined, ligatures are
decomposed, and then all letters `a' are replaced with `z' letters.

\subsection{Image conversion}\label{image-conversion}

It is possible to convert parts of LaTeX input to pictures, it is used
for example for math or diagrams in \texttt{tex4ht}.

These pictures are stored in special \texttt{dvi} file, on which
\texttt{dvi to image} commands are called.

This conversion is normally configured in the \texttt{env file}, which
is system dependent and which has a little bit unintuitive syntax. This
configuration is processed by \texttt{t4ht} application and conversion
commands are called for all pictures.

It is possible to disable \texttt{t4ht} image processing and configure
image conversion in the make file:

\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 table with parameters as argument.

There are three parameters:

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  output - output image file name
\item
  source - \texttt{dvi} file with the pictures
\item
  page - page number of the converted image
\end{itemize}

\subsection{\texttt{mode} variable}\label{mode-variable}

Variable \texttt{mode} contains contents of \texttt{-mode} command line
option. It can be used to run some commands conditionally. For example:

\begin{verbatim}
 if mode == "draft" then
   Make:htlatex{} 
 else
   Make:htlatex{}
   Make:htlatex{}
   Make:htlatex{}
 end
\end{verbatim}

In this example (which is default configuration used by
\texttt{make4ht}), LaTeX is called only once when \texttt{make4ht} is
called with

\begin{verbatim}
make4ht -m draft filename
\end{verbatim}

\section{Command line options}\label{command-line-options}

\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
-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
<filename> (string) Input file name
\end{verbatim}

You can still use \texttt{make4ht} in same way as \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 output dir
making and copying If you want to use them, change the line above to:

\begin{verbatim}
make4ht filename "customcfg, charset=utf-8" " -cunihtf -utf8"  -d foo
\end{verbatim}

This call has the same effect as 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 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}