6  Images

Some portions of your TeX source may be particularly resistant to conversion to HTML. Examples are mathematics and the various approaches to typesetting pictures or diagrams. In such instances, TeX2page invokes a combination of TeX, Dvips [35], Ghostscript [15] and the NetPBM library [31, 32, 33] to produce image files, which are inserted into the HTML output. By default, the image files employ the GIF format. You may change the format to PNG¹¹ or JPEG using the \htmlimgformat command, eg,

\htmlimgformat{png}  % for PNG images 
\htmlimgformat{jpeg} % for JPEG images 
\htmlimgformat{gif}  % for GIF images (default) 

Any TeX fragment enclosed between the control sequences \htmlimg ... \endhtmlimg is converted into an image. Some TeX fragments are automatically converted to images without the need for an explicit \htmlimg. Such fragments are mathematics, calls to the LaTeX picture environment, and MFpic [27] diagrams.¹²

6.1  Mathematics

Math is typically text between $...$ (in-text math) and $$...$$ (displayed math). Here are some samples of mathematics with TeX2page:

$$ F = G {m_1 m_2 \over r^2 } $$ 
 
$$ \int_0^\infty { t - ib \over t^2 + b^2} e^{iat}\,dt = 
e^{ab} E_1(ab), \qquad a, b > 0 $$ 
 
$$ A = 
\left( 
\matrix{ x - \lambda & 1           & 0           \cr 
         0           & x - \lambda & 1           \cr 
         0           & 0           & x - \lambda \cr} 
\right) $$ 

These produce, respectively:

In-text mathematics is also available. Eg,

The Euclidean distance between two points is given by 
$\sqrt{ (\Delta x)^2 + (\Delta y)^2 }$. 

produces

The Euclidean distance between two points is given by .

If the mathematical notation in your text is simple enough not to need images, it is advisable to use \dontuseimgforhtmlmath to force math to be set as text rather than images.

If you do all your mathematics in roman numbers, you can avoid math-related images completely. TeX2page recognizes the TeX command \romannumeral, which produces the roman equivalent of the following arabic number (\romannumeral 1986 = mcmlxxxvi). \romannumeral produces lower-case letters -- tex2page.tex includes \Romannumeral, whose result is all-upper-case (\Romannumeral 1986 = MCMLXXXVI).

6.2  Other image inserts

You may explicitly request any part at all of your TeX document -- not just its math -- to be converted into images for your HTML output. The fragment of the document to be converted to image is enclosed between \htmlimg and \endhtmlimg. This is particularly useful for rendering pictures in HTML. Here's an example TeX-based diagram from The TeXbook [25, p 389]:

\htmlimg 
\newdimen\unit 
\def\point#1 #2 {\rlap{\kern#1\unit 
    \raise#2\unit\hbox{$ 
      \scriptstyle\bullet\;(#1,#2)$}}} 
\unit=\baselineskip 
\centerline{\vtop{\hrule 
  \hbox{\vrule height10\unit depth9.4\unit \kern2\unit 
    \hbox{% 
      \point 0 0 % Alioth (Epsilon Ursae Majoris), mag 1.79 
      \point 0 8 % Dubhe (Alpha Ursae Majoris),    mag 1.81 
      \point 0 -8 % Alkaid (Eta Ursae Majoris),    mag 1.87 
      \point -1 -2.5 % Mizar (Zeta Ursae Majoris), mag 2.26 
      \point 4 7 % Merak (Beta Ursae Majoris),     mag 2.37 
      \point 4 2 % Phekda (Gamma Ursae Majoris),   mag 2.44 
      \point 1 1.5 % Megrez (Delta Ursae Majoris), mag 3.30 
      }%    Src: Atlas of the Universe; Astronomy Data Book 
    \kern7\unit \vrule}\hrule}} 
\endhtmlimg 

This produces the image:

6.3  Image preamble

For any but the most garden-variety mathematics and pictures, you probably have a suite of your own TeX control-sequence definitions (or TeX macro files). You can inform TeX2page of their presence by announcing them as your ``image preamble''. Eg,

\imgpreamble 
  \input some-pic-macs 
  \let\gO\Omega 
  \def\I#1#2{\int_{#1}^#2} 
\endimgpreamble 

You can afterward use the control sequences \gO, \I, and those in some-pic-macs.tex in your mathematical or pictorial text.

It is common to use a drawing tool such as XFig to produce TeX subfiles that typeset as pictures. Let the macros used by these TeX picture files be defined in pepic.tex. Our TeX source can then be:

\input pepic 
 
\imgpreamble 
  \input pepic 
\endimgpreamble 
... 
\htmlimg 
  \centerline{\input picture-file-1 } 
\endhtmlimg 
... 
\htmlimg 
  \centerline{\input picture-file-2 } 
\endhtmlimg 
... 

where picture-file-1.tex, picture-file-2.tex, ..., are the picture files. The first \input pepic is for TeX when it processes the entire document. The second \input pepic, the one inside the image preamble, is used by TeX2page when it processes just the image fragments of the source file through TeX.

6.4  Image magnification

In general, the magnification of the image inserts, whether math or picture, may not match that of the rest of the text in the HTML output. The DVI output has no such problem, because the math and the picture-macros use the same magnification as the surrounding text. In the HTML output, however, the regular text is rendered at the default magnification of your browser, while the images have come via TeX, and the twain may not meet. Typically, the image is too small.

The solution is to adjust the magnification of just the image inserts. In plain TeX, this can be done by a call to the \magnification command inside the image preamble. Eg,

\imgpreamble 
  \magnification\magstep1 
  ... 
\endimgpreamble 

The above will magnify the HTML math and pictures. Note that it will not affect the magnification of these same items in the DVI output. Indeed, you can specify an alternate \magnification outside \imgpreamble, and that will affect overall size of the entire DVI output, inclusive of math and pictures, as advertised in The TeXbook [25].

In sum: \magnification, when called outside the \imgpreamble, magnifies the entire DVI document. When called inside the \imgpreamble, it will magnify just the images in the HTML document. These two uses of \magnification will not interfere.

LaTeX users can use the following, but there must be a better way:

\imgpreamble 
\let\LaTeXdocument\document 
\def\document{\LaTeXdocument\Large} 
\endimgpreamble 

This tacks a hook on to the \document command. (This modified \document will only operate on the image.)

6.5  Reusing image files

\definitions that use math (such as the following one for \ohm) work as expected in the HTML output.

\def\ohm{$\Omega$} 
 
The circuit uses two 10-\ohm\ resistors, three 50-\ohm\ 
resistors and one 1-k\ohm\ resistor. 

produces

The circuit uses two 10- resistors, three 50- resistors and one 1-k resistor.

However, this is very inefficient: Every occurrence of \ohm in the document will generate a brand new image file. To advise TeX2page to reuse the same image for these multiple occurrences, change the \def to an \imgdef:

\imgdef\ohm{$\Omega$} 

6.6  Recycling image files

The conversion of TeX fragments into images can consume a lot of time. TeX2page will therefore recycle existing image files from a previous run, instead of generating them anew. To force generation of new image files, delete the old image files.