Home

Book Errata

RPi4 gpio

x86-64 Hints

LaTeX to HTML

### Background

I used LaTeX to write and typeset the x86-64 book. It has been used in the classroom since 2008 so has been thoroughly "debugged", thanks to feedback from many students. (See the Errata.) The book was originally printed by the campus bookstore as a "reader", which meant that I did not get paid royalties for my work. In 2011 I made a PDF version available, which students preferred to the print version.

This history led me in early 2013 to consider converting the book to an eBook format for sale. I had three goals in mind:

• Increase availability of the book.

It was only being used at Sonoma State University, Santa Rosa Jr. College, and occasionally at the University of San Francisco.

• Strike a balance between reader cost and my being paid for my work.

Textbooks from traditional publishers are expensive. I would like to do my part to help keep the cost to the reader low. On the other hand, creating this book has been a lot of work. Although I've enjoyed it, I think that we all deserve to be paid a reasonable amount for our work.

• Make as few changes to the text as possible.

Since the book had been used successfully for several years and had been well-received, I did want to change it.

With these goals in mind, and knowing almost nothing about eBooks, I began my learning process. I am a big fan of open standards, so I decided that epub would be the best format for my book. Further research taught me that epub is based on xhtml. So what I needed was a process to convert LaTeX to xhtml. The next thing I learned is that this conversion is not straightforward. The real problem is that the features that make LaTeX great for authoring technical works — rendering equations, drawing figures, formatting pages, etc. — are not implemented very well in xhtml; they are "under construction."

This led me to the decision to sell my book in both PDF and print-on-demand paperback versions. Lulu.com was the only place that provided both.

Then in my February 2015 issue of Communications of the ACM I read Do-It-Yourself Textbook Publishing by Armando Fox and David Patterson. They were successful in doing a LaTeX to Kindle conversion, so I was motivated to try again. I did get Prof. Fox's tools to work with my book, but I decided to take a slightly different approach.

Profs. Fox and Patterson sell their book through Amazon, hence the production of a Kindle version. I decided to stay with the PDF and print-on-demand paperback versions at Lulu.com, but add a no-charge HTML online version. Prof. Fox's work provided me the confidence that I could eventually figure out how to produce an HTML version from my LaTeX source without rewriting the content.

The rest of this article describes the steps I took. As you read this, keep in mind that I had not anticipated this process when I originally wrote the text. If I were to start a new text, I would attempt to anticipate the xhtml limitations when deciding which LaTeX features to use.

Also note that this is not intended to be a cookbook, howto presentation. These are only some notes about my experiences and observations. I am sure that there are better ways to do many of these things. And since the LaTeX-formatted versions are available at a reasonable cost, I did not feel compelled to worry too much about the (free) online HTML verson.

Another result of my not using the latest HTML technology is that the online book should be more widely available. Some mobile devices may not handle HTML5, MathJax, or MathML. It seems appropriate to use the "lowest common denominator" for the free online version.

### Using tex4ht

• The first thing I did was to create a mechanism to select between the three versions —paper, PDF, HTML — within the existing LaTeX source code. At the beginning of my main file I used the following code:

     \def\web{0}
\def\pdf{1}
\def\paper{2}
\include{bookType}

where bookType.tex is created by my Makefile with entries like:
     [ ! -f bookType.tex ] || rm -f bookType.tex
echo "\\\\let\doctype=\paper" > bookType.tex


• Following Prof. Fox's example, I decided to use tex4ht for my conversion. The font I was using did not render correctly in the HTML version. Rather than attempt to figure this out, I simply went with another font for the HTML version:

     \ifx\doctype\web
\usepackage{lmodern}
\else
\usepackage{dejavu}
\fi


• I use a monospace font many places in my book, and in some places it is boldface. htlatex does not seem to do this correctly, so I created a configuration file, my.cfg:

     \Preamble{html}
\begin{document}
\Css {.ec-lmtk-10{font-weight: bold;}}
\EndPreamble

which is invoked with my Makefile entry:
     htlatex book.tex "my.cfg,info,2" " -cunihtf" "-cvalidate, -dhtml/"


By the way, I originally tried to create a css entry that had both monospace and bold,

       \Css {.ec-lmtk-10{ font-family: monospace; font-weight: bold;}}

but that did not work. Although it's not clear (to me) in the tex4ht documentation, it seems that the \Css entries will be added to the default entries, not replace them.
• I wanted to use MathML or MathJax for the equations. However, this rendered the equations in SVG. After the first encounter with SVG, the remaining HTML code switched from span markup to tspan, which caused all the font styles, weight, etc. (italic, boldface, etc.) to disappear. I settled for the default, which is to render equations in png.

• The biggest challenge was with my graphics. I used Dwight Aplevich's LaTeX Circuit_macros to create almost all my figures. These macros create tex files that create beautiful drawings. Unfortunately, tex4ht converts these drawings into SVG, which creates the font style problem mentioned above.

So I used the method described by Nasser M. Abbasi (see his hint 3.18) to create a png rendering of each of my figures. Because the png figures do not render as nicely with pdflatex (for my PDF and paper versions), I wrote a macro, bpdrawing, to select the tex or png file for each figure, depending on the document version:

     %% This macro selects the .png version of my drawings for the web
%% and the .tex sources for PDF. Note that it requires that
%% doctype be defined as \web.
\ifx\doctype\web
\newcommand{\bpdrawing}[1]{%
\includegraphics {#1.png}}
\else
\newcommand{\bpdrawing}[1]{%
\input #1}
\fi


• I had written LaTeX things like $V_\mathrm{SS}$ in my m4 source code for the Circuit_macros, which dutifully pass it along. Although latex accepts this, tex4ht does not. And it really should be $V_{\mathrm{SS}}$ anyway. I had to make these changes in the m4 files for processing to correct tex by the Circuit_macros.

• I learned that tex4ht requires that the multicols environment must surround a list environment. For example,

   \begin{multicols}{2}
\begin{list}{\alph{exersub})}{\usecounter{exersub}}
\item \texttt{0100 0101 0110 0111}
\item \texttt{1000 1001 1010 1011}
\item \texttt{1111 1110 1101 1100}
\item \texttt{0000 0010 0101 0000}
\end{list}
\end{multicols}

I had put the multicols within the list, so I had to change all occurrences.

• tex4ht did not handle the math array environment. I had to change things like

     $\begin{array}{rlcl} 1&1& &\longleftarrow carries\\ &67& &\longleftarrow x\\ +&79& &\longleftarrow y\\ \cline{1-3} &46& &\longleftarrow sum \end{array}$

to:
     \begin{center}
\begin{tabular}{rllcl}
\texttt{1}& \texttt{1}  & $\longleftarrow$ carries\\
& \texttt{67} & $\longleftarrow$ x\\
+  & \texttt{79} & $\longleftarrow$ y \\ \cline{1-2}
& \texttt{46} & $\longleftarrow$ sum

\end{tabular}
\end{center}

I had put the multicols within the list, so I had to change all occurrences.

• I learned that tex4ht does not support the algorithm2e package. I changed to the algorithm package.

• I had used the align environment for multiple-line equations. These were rendered differently from the equations written in the equation environment. I learned that it is generally preferable to use the split environment within the equation environment for multiple-line equations, even for the PDF and paper versions. For example,

     $$\begin{split} 1 \times 2^3 + 0 \times 2^2 + 1 \times 2^1 + 1 \times 2^0 &= 8 + 0 + 2 + 1\\ &= 11 \end{split}$$


I'm sure that I've missed something important here. And I've probably made some mistakes or could have done some things a better way. But this meets my needs for now. I hope it helps anyone who is dealing with some of these problems. And, as always, I welcome any corrections or suggestions about how to improve things.