[tex4ht] Multitude of problems when trying to convert from .tex to .html.

[Michal Hoftich]

Hello!

>I am trying to convert some .tex files to .html files (I am hoping to 
>automate this process over the next view days as part of a pipeline), 
>and I ran into a couple of problems doing so. The documentation I found 
>assumes that these problems don't happen, and everything I found so far 
>wasn't able to solve these problems, so I decided I'd just ask for it 
>here directly.

I've downloaded your project and I can compile it. In particular, I 
don't have issues with \tableofcontents, or with \multicolumn. I suspect 
that this may be caused by use of older TeX distribution. Which 
distribution do you use?

There is one fatal issue, related to your \maketitle.

You use the following code:

%%%%%%%%%%%%%%%%%%%%%%%%%
\title{\begin{center}
            %\BeginAccSupp{method=plain,Alt={\GenderRender\\Specification}}
            \includegraphics{images/title-black.pdf}
            %\EndAccSupp{}
\end{center} Template system and implementation specification for rendering gender-neutral email templates with pronoun information}
%%%%%%%%%%%%%%%%%%%%%%%%%

This causes TeX4ht to fail. The problem is caused mainly by use of 
\begin{center}...\end{center} 

It is fortunately simple to fix that. Use custom command that will be 
changed when TeX4ht is used: 


%%%%%%%%%%%%%%%%%%%%%%%%%
\newcommand\titlegraphics[1]{%
\begin{center}%
   \includegraphics{#1}%
\end{center}%
}
% end.

\title{ %\BeginAccSupp{method=plain,Alt={\GenderRender\\Specification}}
            \titlegraphics{images/title-black.pdf}%
            %\EndAccSupp{}
Template system and implementation specification for rendering gender-neutral email templates with pronoun information}
%%%%%%%%%%%%%%%%%%%%%%%%%

You may need to delete the .aux and .xref files to fix the fatal error 
that happens because of code that was inserted to them on the last 
successful run.

All TeX4ht specific stuff can be now fixed in a .cfg file. Save the 
following code as config.cfg:

%%%%%%%%%%%%%%%%%%%%%%%%%%
\Preamble{xhtml}
% support for the \subsubsubsection command
\NewSection\subsubsubsection{}
\Configure{subsubsubsection}{\refstepcounter{subsubsubsection}}{}
{\ifvmode\IgnorePar\fi\EndP\HCode{<h6 
class="subsubsubsection">}\thesubsubsubsection\space}{\HCode{</h6>}}
% fixes for \title
% we need to redefine commands that cause issues here to do nothing
\Configure{@TITLE}{\renewcommand\titlegraphics[1]{}}
\renewcommand\titlegraphics[1]{\ifvmode\IgnorePar\fi\EndP%
\HCode{<div class="titlegraphics">}\includegraphics{#1}\HCode{</div>}}
% add custom CSS
\Configure{AddCss}{myfixes.css}
% change rungs to gs
\Configure{Ghostscript}{gs}
% don't set image size
\Configure{Gin-dim}{}
% images should have maximum width same as display width
\Css{img {
     max-width: 100\%;
     height: auto;
}}
\begin{document}
\EndPreamble
%%%%%%%%%%%%%%%%%%%%%%%%%%%

This configuration file does several things:

1. support for \subsubsubsection command is added. Every sectioning 
command needs special configuration in TeX4ht. Standard \chapter or
\section  commands work out of the box, but new commands needs at least
\NewSection\commandname. 

\Configure{subsubsubsection} defines HTML code that should be used for 
this command. We also handle the counter here.

2. fixes for \title command. Because contents of \title is used in the 
<title> element, which supports only plain text, we need to remove 
everything that may cause issues. In particular the image. This is 
achieved using:

\Configure{@TITLE}{\renewcommand\titlegraphics[1]{}}

This code is executed when <title> is written to the HTML file. It is 
executed in a group, so it doesn't collide with the definition of 
\titlegraphics that is used in \maketitle. Because we don't want image 
in <title>, we can redefine it to just print nothing.

In \maketitle, the following code will be used:

\renewcommand\titlegraphics[1]{\ifvmode\IgnorePar\fi\EndP%
\HCode{<div class="titlegraphics">}\includegraphics{#1}\HCode{</div>}}

It inserts the image inside a <div> element, so you can style it if you 
want. It is centered by default, because the whole contents of 
\maketitle are centered using CSS.

3. custom CSS

Because you may want to change how stuff looks, an external CSS file is 
inserted using \Configure{AddCss}{myfixes.css}

The myfixes.css can look like this:

%%%%%%%%%%%%%%%%%%%
/* Fix heading sizes */
h5.subsubsectionHead{font-size:1em;}
h6.subsubsubsection{font-size:1em;}

/* Set maximum width */
body{
		margin:1em auto;
		max-width:65ch;
		padding:0 .62em;
     line-height: calc(1ex / 0.32);
     /* uncomment following line to set bigger font size */
		/* font:1.2em/1.62 serif; */
}
%%%%%%%%%%%%%%%%%

It fixes sections that are smaller than the paragraph text and defines 
some basic style of your document. You can add more stuff here.


4. images

If rungs is not available on your system, try to change the name of 
Ghostscript command using

\Configure{Ghostscript}{gs}

rungs is used by TeX Live. I believe that it is used also by Miktex. It 
is possible that some Linux distributions use just `gs`.  

Once your PDF file is converted to PNG, run this command:

ebb -x images/*.png

It will create .xbb files with image dimensions for all PNG files in 
your images directory. It will remove TeX4ht warnings about unknown 
image sizes.

---------------------------

With these fixes, I get relatively nice web page. 

To compile your file with this configuration file, run the following 
command:

      make4ht -c config.cfg spec.tex "fn-in"

BTW, I see that you use Github Actions. You can use make4ht in Github 
Actions to compile your file on server and automatically publish on 
Github Pages. I use this method here: 
https://github.com/michal-h21/tex4ht-doc

Best regards,
Michal