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 [34], Ghostscript [14] and the
NetPBM library
[31, 29, 30] 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 PNG12 or JPEG using
the \htmlimageformat
command, eg,
\htmlimageformat{png} % for PNG images \htmlimageformat{jpeg} % for JPEG images \htmlimageformat{gif} % for GIF images (default)
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. 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
.
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 (ie, 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).
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 [43] and The Gimp [15], or algebraic ones like MetaPost [18]. 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 [26], whose TeX macros transform a picture specification inside the document into an external METAFONT [22] 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 produce13
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 \epsfbox
ed 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 [39] 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.
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 [23, 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.
When converting math, EPS, and other implicit or
explicit \htmlimage
s 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.
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
[23].
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.)
\def
initions 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$}
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.
12 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.
13
The file
lambda.mp
was actually written out from this document's
source using \verbwrite
(sec 5.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.