IX  Images

Some portions of your TeX source may be explicitly images, or text that is particularly resistant to conversion to HTML. Examples are JPEGs from digital cameras, encapsulated PostScript inserts, mathematics, and the LaTeX {picture} environment. TeX2page embeds these as images in the HTML output.

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 √( (Δ x)² + (Δ y)² ).

You can control whether your mathematics should be specified as image or ascii with the flag \TZPmathimage (p. 6).

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 Inkscape [22], The Gimp [17], and Xfig [47], or algebraic ones like MetaPost [20]. 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 [30], whose TeX macros transform a picture specification inside the document into an external METAFONT [26] 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} 

These are commands defined external to plain TeX or 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 a generic graphics includer that tackles more than EPS files, based on file extension. Thus, if your file has a nonstandard extension, you will have to inform \includegraphics of this using directives like the following:

\DeclareGraphicsRule{.1}{mps}{*}{} 

This states that files with extension .1 are to be treated as EPS files generated by MetaPost.

\includegraphics is defined in the LaTeX package graphicx.sty, which can also be loaded by plain-TeX documents with the help of miniltx.tex, as we saw with color.sty on p. 4.*

\input miniltx 
\input graphicx.sty 
\resetatcatcode 

Here is an example of an EPS insert: The MetaPost file lambda.mp is processed by MetaPost generating the PS file lambda.1, which we load with

\centerline{\epsfbox{lambda.1}} 

to produce†

  

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.

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 [43] 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: Either use \includegraphics, or a primitive call such as

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

TeX2page recognizes the scaling information supplied with \pdfximage and \includegraphics, with one browser pixel equated to one point. Unlike EPS files, PNG and JPEG images are directly supported by HTML, so TeX2page does not need to convert them.

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 [27, 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.

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 (p. 6). 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”

\ifx\shipout\UnDeFiNeD % HTML only 
  \imgpreamble 
    \input some-pic-macs 
    \let\gO\Omega 
    \def\I#1#2{\int_{#1}^#2} 
  \endimgpreamble 
\fi 

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.

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

\ifx\shipout\UnDeFiNeD 
  \imgpreamble 
    \magnification\magstep1 
    ... 
  \endimgpreamble 
\fi 

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 [27].

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:

\ifx\shipout\UnDeFiNeD 
  \imgpreamble 
    \let\LaTeXdocument\document 
    \def\document{\LaTeXdocument\Large} 
  \endimgpreamble 
\fi 

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

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, use \imgdef for the HTML:

\ifx\shipout\UnDeFiNeD % HTML only 
  \imgdef\ohm{$\Omega$} 
\else 
  \def\ohm{$\Omega$} 
\fi 

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.