# 8  Images

Some portions of your TeX source may be explicitly images, or text that is particularly resistant to conversion to HTML. Examples are encapsulated PostScript inserts, mathematics, and the LaTeX {picture} environment. In such instances, TeX2page invokes a combination of TeX, Dvips [20], Ghostscript [7] and the NetPBM library [17] 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 PNG11 or JPEG using the \htmlimageformat command, e.g.,

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


## 8.1  Mathematics

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

$$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. E.g.,

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 .

You can control whether your mathematics should be specified as image or ascii with the command \htmlmathstyle:

\htmlmathstyle{no-in-text-image} sets in-text math (i.e., math embedded in running text) as ascii. \htmlmathstyle{no-display-image} sets displayed math as ascii. \htmlmathstyle{no-image} abbreviates \htmlmathstyle{no-in-text-image no-display-image} and sets all math as ascii.

\htmlmathstyle{in-text-image}, \htmlmathstyle{display-image}, and \htmlmathstyle{image} respectively set in-text, displayed, and all math as images. By default, \htmlmathstyle{image} holds.

If the mathematical notation in your document is simple enough not to need images, it is advisable to set one or both of the no- options of \htmlmathstyle.

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).

## 8.2  Graphics inclusions

Encapsulated PostScript files (EPS) are a convenient and popular way to insert pictures (graphics) into TeX documents. Users create EPS files with their favorite external programs, which can be GUI tools such as Xfig [26] and The Gimp [8], or algebraic ones like MetaPost [9]. It is also possible to write a picture’s specification in the document, while still relying on an external program to make sense of it. An example is MFpic [14], whose TeX macros transform a picture specification inside the document into an external METAFONT [10] or MetaPost file.

However it is created, an EPS file is typically inserted as a TeX box into a TeX document with calls like

\epsfbox{eps-file}
\includegraphics{eps-file}       % LaTeX only


TeX2page converts such calls into images. Here is an example: The MetaPost file lambda.mp is processed by MetaPost generating the PS file lambda.1, which we load with

\centerline{\epsfbox{lambda.1}}


to produce12

For \epsfbox, you can specify the desired image width and height by assigning to the dimen registers \epsfxsize and \epsfysize (specifying only one of them will cause the other to change as well, maintaining the image’s aspect ratio). TeX2page will respect such sizes, equating one browser pixel to one point (= 1/72.27 inch). Thus,

\epsfxsize=1.5in


sets the width of an immediately following \epsfboxed image to 1.5 × 72.27 ~ 108 pixels. \epsfxsize and \epsfysize are cleared after each \epsfbox.

Note that \epsfbox and \includegraphics are defined external to plain TeX and LaTeX. Plain TeX documents using \epsfbox must load the standard macro file called epsf.tex. LaTeX documents using \epsfbox can do the same, or they can load the epsfig.sty package. \includegraphics is available only to LaTeX, and is defined in the package graphicx.sty.

If you use the PDF versions of TeX (which produce PDF instead of DVI output), you can insert MetaPost-created EPS files with the \convertMPtoPDF command:

\convertMPtoPDF{eps-file}{1}{1}


\convertMPtoPDF is defined in the macro file supp-pdf.tex of the ConTeXt [23] package, which is included in most modern distributions of TeX. Caveat: \convertMPtoPDF doesn’t work for EPS files that weren’t made using MetaPost.

PDF versions of TeX can import common graphics formats such PNG and JPEG. PDF LaTeX uses \includegraphics as before, whereas in PDF plain TeX, a command like

\pdfximage height 1.5in {pic.png}\pdfrefximage\pdflastxmimage


is used. TeX2page recognizes \pdfximage including the scaling information, with one browser pixel equated to one point.

## 8.3  Other image inserts

You may explicitly request any part at all of your TeX document — not just its math or EPS inserts — to be converted into images for your HTML output. The fragment of the document to be converted to image is given as an \makehtmlimage argument. Here’s an example TeX-based diagram from The TeXbook [11, p 389]:

\makehtmlimage{
\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}}
}



This produces the image:

\makehtmlimage’s argument is a group containing no unmatched braces.

## 8.4  Image preamble

When converting math, EPS, and other implicit or explicit \htmlimages into images for HTML, TeX2page extracts the small fragment of the TeX document containing the would-be image into a separate, smaller TeX file. The content of this auxiliary TeX file is then cajoled by a bevy of external programs into an image file suitable for HTML. This demands that all the TeX code within the auxiliary TeX file be self-sufficient. However, it is quite possible that such TeX fragments contain references to macros defined elsewhere in the larger document. TeX2page therefore provides the \imgpreamble ... \endimgpreamble environment, into which are placed all definitions that are necessary for the HTML images. For example, the “image preamble”

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


allows the use of the control sequences \gO, \I, and those in some-pic-macs.tex in the TeX fragments destined for imagehood.

The commands inside \imgpreamble are visible only to TeX2page, so a form of them should also be specified outside the \imgpreamble for use by TeX when it processes the entire document for DVI.

Note that if you use encapsulated PostScript inserts, it is not necessary (though it doesn’t hurt) to specify an image preamble for loading the epsf.tex macro file or graphicx.sty package. TeX2page will automatically load them when processing the EPS files. You still need to load these files outside the image preamble for your document to be processable by TeX though.

## 8.5  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. E.g.,

\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 [11].

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:

\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.)

## 8.6  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$}


## 8.7  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.

11 PNG would have been the default image format of choice, were it not for the fact that browser support for transparent PNGs is currently poor. If your HTML background color is pure white, PNG is a good choice as lack of transparency is not a concern.

12 The file lambda.mp was actually written out from this document’s source using \verbwrite (sec. 6.3), so the file lambda.1 isn’t immediately available. Nevertheless, TeX2page will take care to call MetaPost on the generated lambda.mp file, ensuring that the EPS file is available for conversion into an HTML image. In contrast, when getting the DVI version of the document via TeX, it is the user’s responsibility to call MetaPost on generated files, and call TeX again. Unfortunately, commands like \epsfbox and \includegraphics, when they do not find their argument file, will signal error and cause TeX to go into a debug loop, even though the MetaPost file needed for their creation can only be created if TeX successfully finishes processing the source document! To force TeX to finish processing the source file regardless of missing EPS files, you need to run it in \scrollmode, or its even more reckless cousins \nonstopmode and \batchmode. One way to get into these modes is to type s, r, or q, respectively, at the TeX debug prompt. By default, TeX runs in \errorstopmode, which is why it stops on the missing-file error.