Chapter 9
FAQ and Troubleshooting

9.1 General Advice

In general, don’t postpone your conversion to the last moment. As you will most likely want to produce ebook or HTML versions of LaTeX documents these days, you should try the conversion of your document from the beginning.

It is much easier to fix errors as soon as they appear. Often, one issue can cause many issues that follows, and it can be really hard to find the culprit.

Compile your document using TeX4ht every time you add a new package, as the included code can break other packages or even LaTeX kernel. You may also find that you will need a different definitions for some commands for the HTML conversion, as the version suitable for PDF produce some artifacts from drawing commands. These issues are also best to fix as soon as possible.

If you cannot find the solution for your error yourself, you can report it to one of the following channels:

9.2 Compilation Errors

In the case of error, always try to run make4ht in the debugging mode. It will provide the full terminal output, and stop on errors: 

$ make4ht -a debug foo.tex

In many cases, fix of the first error can resolve the following errors.

Packages that cause issues TeX4ht can sometimes clash with other packages. If you don’t need features the problematic package provides (typically, they modify stuff that makes sense in the PDF output, but not in HTML, like page headers, fancy section titles, etc.), an easiest fix is to disable their loading when TeX4ht is active.

The easiest way to disable package from loading is to add the following condition to your document preamble: 

\ifdefined\HCode 
... code for TeX4ht 
\else 
\usepackage{foo} 
\fi

Fragile commands Some commands may cause compilation errors when used in \section or \caption arguments. These errors usually show when the document preamble stops and auxilary files are loaded. They can be quite hard to debug.

Consider the following example: 

\begin{figure}[h] 
\includegraphics{example-image} 
\caption{$\begin{array}{c c} hello & world\end{array}$} 
\end{figure}

It produces a fatal error: 

[ERROR]   htlatex: Compilation errors in the htlatex run 
[ERROR]   htlatex: Filename     Line    Message 
[ERROR]   htlatex: ./minimal.tex        7        Argument of \im:g has an extra }. 
[ERROR]   htlatex: ./minimal.tex        7        Paragraph ended before \im:g was complete. 
[ERROR]   htlatex: ?    ?        Incomplete \iffalse; all text was ignored after line 7. 
[ERROR]   htlatex: ?    ?        Emergency stop. 
[FATAL]   make4ht-lib: Fatal error. Command htlatex returned exit code 1

You can get more context for this error using the -a debug option for make4ht: 

! Argument of \im:g has an extra }. 
<inserted text> 
                \par 
l.7 ...egin{array}{c c} hello & world\end{array}}

The error itself is pretty cryptic, but you can see that the cause is in 

\caption{$\begin{array}{c c} hello & world\end{array}$}

The issue is that some commands needs to be protected when used in parameters of \section or \caption commands. There are two possible fixes. First is to use the \protect command: 

\caption{$\protect\begin{array}{c c} hello & world\protect\end{array}$}

Other fix is to use the writetoc configuration: 

\Configure{writetoc}{% 
\def\begin{\detokenize{\begin}} 
\def\end{\detokenize{\end}} 
}

In this configuration, we redefine \begin and \end commands to print their verbatim contents when they are used. They will be then written to the auxilary file thanks to this configuration. Redefinitions that happen in writetoc are active only when stuff is written to the auxilary files, so you don’t need to worry that it will break normal handling of environments.

Last tip for dealing with errors that involve auxilary files is to delete temporary files if the error is fatal. In that case the temporary file will not be overwritten with a fixed version, resulting in fatal error even if you fixed the original issue. It is recommended to remove at least the .aux and .xref files, but you may need to remove also .4tc and .4ct files. To simplify this process, you can use the clean mode of make4ht: 

$ make4ht -m clean filename.tex

It will remove all temporary files, but also generated HTML files and images.

9.3 DOM Processing Errors

TeX4ht post-process generated HTML and XML files using Lua filters. They fixes various issues that are not possible fix on the TeX level, and also add some additional features. For example, the MathML output relies on filters to produce valid code.

These filters use the LuaXML library for the processing. When the generated HTML or XML file is not well-formed, you may get the following warning: 

[WARNING] domfilter: DOM parsing of test.html failed: 
[WARNING] domfilter: /home/michal/texmf/scripts/lua/LuaXML/ 
luaxml-mod-xml.lua:175: Unbalanced Tag (/p) [char=1353]

This means that DOM parsing failed and filters cannot be applied. This will result in incorrect file.

Incorrect handling of paragraphs Common cause of this issue is incorect handling of paragraphs in commands that produce block level elements such as <div> or <section> elements.

Say that you have a following code in your document: 

\newenvironment{test}{\itshape}{} 
 
\begin{test} 
world 
 
more paragraphs 
\end{test}

And that you configure the test environment to to produce a custom <div> element: 

\ConfigureEnv{test}{\HCode{<div class="test">}}{\HCode{</div>}}{}{}

This configuration will break the LuaXML parsing, as it produces invalid HTML code: 

<!--l. 27--><p class="indent" >   <div class="test"> <span 
class="cmti-12">world</span> 
</p><!--l. 30--><p class="indent" >   <span 
class="cmti-12">more paragraphs</span> 
</div> 
</p>

The issue is that <p> elements are mismatched. It is necessary that closing </p> tag is inserted before <div> tag. You can use commands introduced in section Paragraph Handling (7.3.4) for this task. The correct configuration can look like this: 

\ConfigureEnv{test}{\ifvmode\IgnorePar\fi\EndP\HCode{<div class="test">}\par} 
{\ifvmode\IgnorePar\fi\EndP\HCode{</div>}\par}{}{}

The \EndP inserts closing </p> tag. But new paragraph still could be started before <div> if we are in the vertical mode, so we need to use also the \ifvmode\IgnorePar\fi command. This will prevent starting of the new paragraph too early. But we want to start a new paragraph after <div>, so we need to use explicit \par after \HCode. Similar paragraph treatment is needed also for the closing of the environment. The resulting HTML with this configuration is correct: 

<div class='test'> 
<!-- l. 28 --><p class='indent'>   <span class='cmti-12'>world</span> 
</p><!-- l. 30 --><p class='indent'>   <span class='cmti-12'>more paragraphs</span> 
</p></div>

9.4 Math Issues

9.4.1 Problems With MathML

Single delimiters Use of single delimiters like $\langle$ may result in invalid MathML code. TeX4ht can try to fix that using the mathml- option.

Use of \hbox in math environments

Don’t use the \hbox command inside math environments. The following code results in DOM error and wrong rendering by MathML processors. You can fix this by using \mbox instead. 

\begin{equation*} 
  \begin{array}{ll} 
      \frac{k}{2^{n}}, & \hbox{ if \(\frac{k-1}{2^{n}}\leq\tau < \frac{k}{2^{n}}\).} 
  \end{array} 
\end{equation*}

9.5 Issues With Packages

9.5.1 Hyperref Issues

Fragile commands in captions The hyperref package loads automatically also the nameref package. It then saves contents of section titles or captions in the auxilary file, so they can be then retrieved using the \nameref command. This leads to various problems with the \caption command, where some commands, such as \index or \label could cause fatal errors.

We fixed these problematic commands, but it is possible that you will experience issues also with other commands. You can declare these commands to do nothing, or to be passed literaly to the auxilary file, using this configuration: 

\Configure{CaptionCommandsFix}{% 
% pass \left unexpanded to the aux file 
\DeclareRobustCommand\left{} 
% disable \index 
\let\index\@gobble% 
}