Retrieve hardcopyStarlink System Note 71.0
Norman Gray
14 June 1999. Release 0.9-6. Last updated 12 January 2001
This application processes a DVI file produced by TEX, converting each page to a single bitmap. The conversion is done directly, rather than through a chain of intermediate file formats, making the process extremely fast. It can produce output as XBM, GIF and PNG files.
It is sometimes useful to convert the typeset output of TEX into a bitmap image viewable on the web. This is most often the case whenTEX or LaTEX are being used to typeset the mathematics in a paper being conveted to HTML. It is possible to do this with a chain of general-purpose tools, for example going from DVI to postscript to PNM files to GIFs, but this is generally slow. For an overview of maths and SGML/HTML, see Appendix A.
The tool dvi2bitmap does this processing in a single step, reading the DVI file and font files, and emitting a bitmap. It can, at present, generate XBM, GIF and, if the relevant library is installed, PNG files.
See Section 2 for usage instructions, and Section 3 for installation instructions.
The dvi2bitmap application is available for download at
<http://www.astro.gla.ac.uk/users/norman/star/dvi2bitmap/>.
This HTML documentation is also available as a
single file
This document matches version 0.9-6
of the program (you
can see what version you have with the command dvi2bitmap -V).
This should currently be regarded as beta software.
Synopsis:
dvi2bitmap
[-b(h|w) size] [-bp a4|a4l|usletter...]
[-[Cc][lrtb] size] [-fp PKpath ] [-fm mfmode] [-fg] [-fG]
[-g[dpribmg]] [-l num] [-m magmag ] [-n[n]] [-o outfile-pattern]
[-p num] [-pp ranges] [-P[bBtTcC]] [-q[q]] [-Q[FfGgtbp]]
[-r resolution] [-R[fb] int,int,int] [-s scale-factor]
[-t xbm|gif|png] [-V]
dvi-fileThis program is intended to conform to the DVI processing standard.
The motivation for this program was the need for a helper program to produce small bitmaps for inclusion in web pages. Accordingly, the program's underlying usage model is that one would generate a file ofTEX or LaTEX material, convert it to a DVI file using TEX, and convert the result to a collection of bitmap files. The input text will typically be equations, but any other TEX material will work as well. For example, the processor which generates the HTML could spit out a file such as
\documentclass{article}
\pagestyle{empty}
\begin{document}
$E=mc^2$
\newpage
% etc...
\end{document}I hope that the program is (or can be made to be) flexible enough to support other modes of use.
-bh size, -bw sizeWarning: p.12: bitmap too big:
occupies (1183,1072)...(4134,6255). Requested 4100x6200, then
you'll need to specify a bitmap size. The numbers
(1183,1072)...(4134,6255) are the coordinates of the top-left and
bottom-right of the bitmap: in this case -bh 6300 -bw
4200 would suffice. Note that the `h' in -bh stands for
height, not horizontal! At some point, I'd like to make the bitmap
`expandable', obviating the need for these options.-bp papersize-Qp. This is useful either to make sure that
there is enough room on the initial bitmap, to avoid the warning
above, or, along with the -PC option, to force the output
bitmap to be a certain size.-c[edge] dimen, -C[edge] dimen-c and -C options allow you to control how the
generated bitmaps are cropped before they are written. The
[edge] may be one of `l', `r', `t' or `b', referring to the
left, right, top and bottom edge of the bitmap, or be missing, in
which case it refers to all four sides. In the case of the -c
option, this sets the crop to be dimen points from the
specified edge of the
bounding box of the blackened pixels; in the case of the -C
option, it sets it to be dimen points from the left or top of
the `page'. The specification -C dimen, which would set all
the crops to the same position, is silly, and so is forbidden.The conversion from points to pixels takes account of the
magnification set in the -m option, if that's been specified
already, but it doesn't notice if that's set after this option, and it
takes no account of any magnification in the DVI file.
See Section 2.2 for TEX \special commands which
set this within the TEX file.
-fp font-path-fm modeibmvga, but see
--enable-fontgen in Section 3.1.-fg-fG-g(d|p|r|i|b|m|g)-l pagenum-p-m magnification-n-Qf and -Qg
options. If this option is present, then the program returns non-zero
if any fonts were missing (see also Section 2.3).-nn-Q.-o output%d
formatting descriptor, which will be replaced in output filenames
with the page number. This can be overridden on a per-page basis by
a TEX \special embedded in the DVI file (see item `outputfile <filename>' in Section 2.2). If there is no
file extension, or if it does not match the output type, a suitable file
extension will be added.-p pnum, -l lnum, -pp pagelistdvips (and the same option letters).The -p and -l options take single page numbers; if
either of these is given, then the program will process pages from
page pnum to page lnum, with the defaults being the
corresponding extremes. The pagelist consists of a
comma-separated sequence of page numbers and ranges (a-b); only
those pages, and the pages falling in those ranges (inclusive of the
end pages) are processed. Any of these specifications may be prefixed
by either `=' or `:n,'. In the former case, DVI page
numbers are used rather than TEX \count registers; in the
latter case, the program examines the \count
register
rather than the default \count0.
You can specify both of these prefixes one or more times, but you
cannot mix the -p and -l options with the -pp
option. The program will respect only the last -p and
-l options, but the -pp options are cumulative. There
may be no spaces in the pagelist. The page numbers may be
negative.
Examples:
dvi2bitmap -pp 3,6-10 ... # process only the specified pages dvi2bitmap -pp :2,1 ... # process only pages where \count2 was 1
-P[BbTtCc]-Pb blurs the bitmap, making a half-hearted attempt to make a
low-resolution bitmap look better. This really isn't up to much - if
you have the fonts available, or are prepared to wait for them to be
generated, a better way is to use the -m option to magnify the
DVI file, and then the -s option to scale it back down to the
correct size.
The -Pt option makes the output bitmap have a transparent
background, if
that's supported by the particular format you choose using option
-t.
The -Pc option specifies that you want the output bitmap to
be cropped. This is done by default, so you'll more often use the
-PC option to specify that you don't want the output
cropped (for example, if you're using the -bp option and want
the output to stay the specified size).
The options -PB, -PC and -PT disable blurring,
cropping, and transparency, respectively.
By default, bitmaps are not blurred, are cropped, and are transparent if possible.
For PNG files, the output bitmap uses a
palette plus an alpha channel; these are calculated in such a way that
if you display the resulting bitmap on the same colour background as
dvi2bitmap was using (which is white by default, but can be
specified using the background special) then
the result should look identical to the result with no transparency
information, but probably progressively worse the further the
background moves from this. I suppose, but can't at present check,
that this implies that you should choose a mid-grey background colour
when making such transparent PNGs. I'd welcome advice on this point.
-q-qq-Q...-QF option would start QF cmbx10
110 ....Some of these options (-Qf, -Qg) are probably most
useful with the -n option, to investigate a DVI file before
processing. Others (-Qt, -Qp) are probably useful only
with -nn. -Qb is only useful if you do actually
generate bitmaps. For consistency (and so you don't have to remember which
ones do which), neither -n nor -nn is implied in any of
them, and you have to give it explicitly.
-Qb-QfQf', then five fields: the
font name, the DPI value it was looking for, the base-DPI of the
font, the magnification factor, and a dummy metafont mode. This
output might be massaged for use with the mktexpk (TeXLive) or
MakeTeXPK (teTeX) scripts to generate the required fonts, but
-Qg is more straightforward.-QF-Qf, except that found fonts are also listed,
prefixed by `QF'.-Qg-Qf, except that the output consists of the string
`Qg' followed by a mktexpk or MakeTeXPK command
which can be used to generate the font.-QG-Qf, except that found fonts are also listed,
prefixed by `QG'. Only one of
-Qf, -QF, -Qg and -QG should be specified
- if more than one appears, only the last one is respected.-Qp-bp option.-Qt-r resolution--enable-fontgen in Section 3.1.-R[fb] int,int,int-Rf) or background (-Rb)
colour, as an RGB triple (-R stands for RGB: -c was
already in use). The integers must be in the range [0,255], and can
be specified in decimal, octal or hex (ie, 127=0177=0x7f).-s scalefactorscalefactor (default 1).-t typepng, xbm or
gif. The GIF and PNG options may not be available if they
weren't selected when the program was configured.-Vdvi2bitmap recognises several DVI special commands, and emits a warning if it finds any others.
The syntax of the special commands is
\special{dvi2bitmap <special-command>+ }<special-command>
sequences within a single special.The <special-command> which the program
recognises are:
defaultoutputfile <filename>filename.gif (if the output type were `gif'). A filename
extension will be added if none is
present, or if it does not match the output type selected. If the
default command has been given, then this instead specifies the
default filename pattern, and the `filename' should contain a single
#-sign.absolutecrop command.crop <side> <dimen><dimen> points away from the bounding box
of the blackened pixels. <side> may be one of `left',
`right', `top', `bottom' or `all', referring to the corresponding
edge, or all four edges at once. If the default command has
been given in this special, then this pattern of cropping is
additionally made the default for subsequent pages. If the
absolute command has been given, then the crop position is set
at <dimen> points from the appropriate edge of the
`paper'.The -c and -C command-line options
(Section 2.1) have the effect of setting initial defaults.
In the absence of either of these, the initial crop is exactly at the
bounding box.
default imageformat <format>-t option (section Section 2.1).The keyword is just imageformat, but you must specify the
default keyword when you
specify imageformat; this is for consistency, and makes it
clear that this is setting a default format rather than setting the
format only for the next image (that's not implemented at present, but
could be added).
default foreground|background red green
blueimageformat
you should at present always include the default keyword when
using this special. The integers must be in the range [0,255], and can
be specified in decimal, octal or hex (ie, 127=0177=0x7f).strut left right top bottom\strut won't work: that would leave the appropriate space
when TeXing the file, but that space doesn't explicitly appear in the
DVI file (which is just a bunch of characters and locations), so when
dvi2bitmap fits its tight bounding box to the blackened pixels
in the file, it knows nothing of the extra space you want.The `strut' special forces the bounding box to be at least `left', `right', `top' and `bottom' points away from the position in the file where this special appears. All the dimensions must be positive, and they are floats rather than integers.
If you wanted to set a page containing only the maths
`${}^\circ$' (why, is another matter), dvi2bitmap would
normally make a tight bounding box for the bitmap, so that you'd get
an image containing only the circle (unless other crop options were in
force). If, in this case, you put in a special such as
\special{dvi2bitmap strut 0 2 10 2.5}, you would force
the bounding box to come no closer than 0pt to the left of the
position in the file where this special appears, 2pt to the right,
10pt above and 2.5pt below.
A useful bit of TeX magic is:
{\catcode`p=12 \catcode`t=12 \gdef\DB@PT#1pt{#1}}
\def\DBstrut{\strut\special{dvi2bitmap strut 0 0
\expandafter\DB@PT\the\ht\strutbox\space\expandafter\DB@PT\the\dp\strutbox}}\DBstrut will put an
appropriate strut in the output.For example, the pair of commands
\special{dvi2bitmap default outputfile trial-#.gif crop all 5}
\special{dvi2bitmap absolute crop left 0}Exits with a non-zero status if there were any processing errors. Having no fonts present counts as a processing error.
If there is at least one font present, then missing fonts will be
replaced by the first cmr10 font it finds, or a more-or-less
randomly chosen alternative if that font is not used at all. The
program will produce a warning if the -q option is not present,
but it will return with a zero (success) status.
Exception: If the -n option (see Section 2.1) is
present, then the program returns success only if all fonts are present.
This converts the file% dvi2bitmap -r 110 -m 2 -s 2 -t gif hello.dvi
hello.dvi to a GIF bitmap. It first sets the
magnification factor to 2, so that the program uses a double-size font
(eg, .../cmr10.220pk), then scales the bitmap down by a
factor of 2 to obtain a bitmap of the correct size.This reads the DVI file to find out what fonts are required, but does not process it further. It then tries to find the fonts, fails, and produces a list of parameters which could be used to generate the font files.% dvi2bitmap -n -Qf -r 110 -m 1.5 -q hello.dvi Qf cmr10 165 110 1.5 localfont
See also Section 2.5.
The program searches in up to three places for fonts.
-fp option (see item `-fp font-path') specifies a
colon-separated list of directories which should be searched for font
PK files. If this is given on the command line, it overrides...DVI2BITMAP_PK_PATH environment variable, if defined,
specifies a colon-separated list of directories which are to be
searched for PK files.kpathsea
library (see Section 3.1), then it should find PK
files using the same mechanism other DVI processors use.The third method is the ideal - you should build dvi2bitmap
using the kpathsea library if possible (see Section 3.1.1 for how to obtain it): it is because other
DVI-processing programs like dvips and xdvi are built
with the kpathsea library, that you normally never have to
worry about where fonts live. The kpathsea library is
generally integrated with the font-generation commands, and can be
queried using the kpsewhich command.
If you don't, or can't, use the kpathsea library, you have
to let dvi2bitmap know where to find fonts. How, then, do you
establish a list of directories containing suitable PK
files? If your system has the kpsewhich command, then you can
ask it where fonts live. As long as you have at least one font built
for dvi2bitmap, say cmr10.110pk, then kpsewhich
can tell you where it is:
You can use that to set% kpsewhich pk cmr10.110pk /local2/TeX-local/fonts/pk/ibmvga/public/cm/cmr10.110pk
DVI2BITMAP_PK_PATH as follows.
depending on whether you're using a sh-type shell (sh% DVI2BITMAP_PK_PATH=`kpsewhich pk cmr10.110pk | sed 's+/[^/]*$++'` csh% setenv DVI2BITMAP_PK_PATH `kpsewhich pk cmr10.110pk | sed 's+/[^/]*$++'`
sh or
bash) or a csh-type shell (csh, tcsh). Given
that you enabled (or at least, did not disable) font-generation at
configure-time, dvi2bitmap should generate missing fonts in
future, and place them in this same directory.How do you build that first font? Try running dvi2bitmap on
a simple DVI file, with the options -n -Qg: that makes
dvi2bitmap merely examine the list of fonts (-n) and
display commands to generate missing fonts (-Qg). Run one of
these font-generation commands, then ask kpsewhich where the
result is.
It is a good idea to run the dvi2bitmap tests, by giving the
command make test in the build directory. If you do, then you
will end up with at least cmr10 built using the Metafont mode
and point size which dvi2bitmap uses by default (you can change
the default Metafont mode: see item `-fm mode' or item `--enable-fontgen
'). The test script will also give you
an indication of how to set the DVI2BITMAP_PK_PATH variable.
Note that the advice this script gives relies on a rather specific
assumption about how your font-building script (ie, mktexpk or
MakeTeXPK) works: namely that all the fonts built for a
particular Metafont mode and size will be placed in the same
directory. This is true for for the font-building scripts I know
about, but it's not any sort of formal standard, so your local
system's behaviour may quite reasonably be different, in which case
this script can't offer very reliable help.
There are one or two possible wrinkles with the third method. The path-searching library is very powerful and flexible, but it is possible to be tripped up by its configuration file.
Firstly, the program has to find the configuration file. The
program should sort this out for itself at configuration time, but it
is possible that you might have to give it some help. If you specify the
TEXMFCNF environment variable, setting it to the directory
which contains your TEX installation's texmf.cnf file, then
this overrides the program's notion of where the configuration should
be. You can find this file using the command kpsewhich cnf
texmf.cnf.
It can sometimes happen that dvi2bitmap fails to find fonts,
successfully calls mktexpk to build them, but then still
fails to find them, even though mktexpk has put them where they
should be. There are (at least) three possible reasons for this.
If you are using the kpathsea library, there might be some
misconfiguration which is confusing it. You can trace
kpathsea's deliberations in great detail by giving the option
-ggp (item `-g(d|p|r|i|b|m|g)').
Perhaps you do not have the kpathsea library installed, or
have disabled it, but you have requested that font-generation be
enabled (see Section 3.1). What happens in this case
is that mktexpk successfully builds the fonts, and installs
them in the correct place, where `correct place' means `the place
where kpathsea would find them'; you're not using
kpathsea, so no fonts for you. What you have to do in this
case is work out where the `correct place' is (kpsepath and
kpsewhich can help here), and specify that place using either
the -fp option or the DVI2BITMAP_PK_PATH variable, as
above (this is confusing, I know, but more-or-less unavoidable, since
we are here trying to do kpathsea's job, without kpathsea).
Another, slightly nastier reason is as follows.
Some texmf.cnf files declare the location of the
user-writable font directory though a setting like
whereas others have something likeVARTEXFONTS=$SELFAUTOPARENT/var/lib/texmf
Now,VARTEXFONTS=$TEXMFLOCAL/fonts
$SELFAUTOPARENT is a variable which is set
by the kpathsea library to be the grandparent directory of the executable
which uses the library. So, for /usr/bin/{tex,latex,mktexpk,...},
it's /, but if your dvi2bitmap binary doesn't live
with the other dvi-ware then its $SELFAUTOPARENT will be
different, so that dvi2bitmap will look for fonts in a
different place from the place where mktexpk put them when
it successfully generated them.I would argue fairly strongly that having the VARTEXFONTS
directory depend on the location of the dvi-ware executables is
a very silly thing to do. This was the case in the teTeX distribution
which came with RedHat 6.0, though this was fixed pretty rapidly. If
you've fallen foul of this, then you can either
texmf.cnf file to something more like the
second example above; ordvi2bitmap along with the other TEXware.A third option is to get dvi2bitmap to work around the
problem, by telling it to claim to be some program which is
installed along with the other dvi-ware. You do this with the
--enable-fake-progname option to the configuration
script. See Section 3.1 for details.
If you didn't enable automatic font-generation, or if you did and
something went wrong, you might have to generate fonts by hand. You
need to look at the documentation for your TEX system, specifically
the mktexpk and MakeTeXPK scripts (one of which might be
just an interface to the other).
See the discussion of the `make test' script in Section 2.5.1. Also, note that the option -Qg, given to
dvi2bitmap, displays the font-generation commands which would
be required to build the fonts missing from the specified DVI file.
These are the commands which dvi2bitmap would employ to generate
these fonts, when automatic-font-generation is enabled.
Since dvi2bitmap's default resolution is 72 dpi, as opposed to the usual printer resolution of 300 or 600 dpi, you are unlikely to have suitable fonts on your system, and will need to generate them. The program will generate these automatically, if it was configured with support for that (see Section 3.1); if it wasn't configured with that support, or if the automatic font generation fails, you might need to generate the fonts by hand.
How you generate fonts depends on your TEX distribution. As explained
in Section 2.4, you can determine which fonts you need using the
-Qf option. The teTeX and TeXLive TEX distributions include
scripts to
generate fonts for you; if you have a different distribution, there
might be a similar script for you to use, or you might have to do it
by hand. In the case of teTeX, the command you'd use in the
example above would be:
This would generate fonts using the% MakeTeXPK cmr10 165 110 1.5 ibmvga
ibmvga Metafont mode, using
a base resolution of 110 dpi (the default for that mode), at a
magnification of 1.5 times, giving a resultant resolution of 165 dpi.If you're using the TeXLive distribution, the equivalent command would be:
% mktexpk --mfmode ibmvga --mag 1.5 --bdpi 110 --dpi 165 cmr10
If you want to use the same mode as you use for printing documents,
then the mode localfont should do the right thing. Otherwise,
and probably better if these images are intended for the screen rather
than paper, you could use a more specialised mode such as
ibmvga, which has been tweaked to be readable at small
resolutions. See the file modes.mf somewhere in your metafont
distribution for the list of possibilities.
After you have created the fonts, try giving the command
to confirm that TEX and friends can find the new fonts, and that your dvi2bitmap environment variable is set correctly. This command is part of the% kpsewhich pk cmr10.165pk
kpathsea distribution, rather than the core TEX
distribution, so may not be present on your system.dvi2bitmap is packaged in two slightly different ways, one which respects the bundling conventions of the Starlink Project, and one which is more usual for network-distributed software.
When you unpack the distribution tarball, you should find at least
the files dvi2bitmap_source.tar, Makefile.starlink and
mk. If you're on a Starlink machine, you can, and should,
build the software the Starlink way, using the mk script (see
Section 3.2); but if you're not, you should unpack the
dvi2bitmap_source.tar file, and build it the conventional way
(see Section 3.1). Since the Starlink mk
script is really just a driver for the Makefile within the tar file,
you should get the same results both ways.
To configure and build:
but see the configuration options below.% ./configure % make
It's a good idea to run `make test' as well. See Section 2.5.1.
To install, just copy the executable dvi2bitmap wherever you want it
to live.
You can customise the program using flags to the
./configure command:
--with-kpathsea and --without-kpathseakpathsea library (see Section 2.5.1) but don't, for some
reason, want to use it, then give the configure option
--without-kpathsea. By default, the configuration enables
use of the library if it is installed (that is, if the kpathsea include
files and library are somewhere the compiler will find them. If
kpathsea is disabled (by default or by request), then fonts
will not be generated by default.If you have the kpathsea library, but it is not in the
standard place, then you can provide an argument to the
--with-kpathsea option giving the name of a directory
below which are directories include and lib,
containing the required kpathsea include files and library.
If you don't have the
kpathsea library available, see below (Section 3.1.1)
for notes on obtaining it.
--disable-texmfcnfkpathsea library finds its configuration files in two
ways, either automatically if it is installed in the same directory as
the rest of
the TEXware, or using the TEXMFCNF environment variable. The
dvi2bitmap program sets the latter variable internally, unless
it finds it already set. If this will be inconvenient, you can
suppress this behaviour by providing the flag
--disable-texmfcnf, or equivalently
--enable-texmfcnf=no.--enable-fontgenibmvga, which has a resolution of
110 dots-per-inch.The default for this option is `on' - the program will attempt to
generate fonts. Do note, however, that if the kpathsea library
is not enabled, then the program will not be able to find the
fonts it generates, unless you configure it correctly using either
-fp or DVI2BITMAP_PK_PATH (see Section 2.5.1).
If you wish to disable this automatic font
generation, give the option --disable-fontgen.
Note that this does not completely disable font generation - it
merely sets the default for font generation to `off', and it can be
switched back on again using the option -fG.
If you wish
to change the default mode, you can do so with an argument to this
option. For example, the option
--enable-fontgen=pcprevw,118 will make pcprevw,
which has a resolution of 118 dpi, the default MetaFont mode. Note
that the resolution you specify must match the mode: see file
modes.mf for a list of modes and resolutions (use
kpsewhich mf modes.mf to find this). You can change the
resolution and mode on the fly using the -fm and -r
options to the compiled program (Section 2.1).
--enable-mktexpk and --enable-maketexpkmktexpk then MakeTeXPK, and uses whichever it
finds first. If you have both scripts but wish to use
MakeTeXPK for some reason, you will have to give the option
--disable-mktexpk; if you wish to disable both, you will
have to give --disable-maketexpk as well. Both options
take an optional argument giving the path to an alternative script
with the same calling interface.--enable-png (default: enabled)--disable-png.--enable-gif (default: disabled)--enable-gif. The GIF format is the copyright of
CompuServe. As far as I understand it, one does not need a licence
from CompuServe if one is distributing non-commercial, not-for-profit
software, such as this. You probably shouldn't enable GIF support
when you build this program unless you're in that category as well.
But don't listen to me: there's a much fuller account of the whole
sorry business in the comp.graphics.misc FAQ--enable-fake-prognamedvi2bitmap to
have the expected behaviour when (a) you do not install
dvi2bitmap along with the other dvi-ware, and (b) your
texmf.cnf file has VARTEXFONTS or similar dependence on one
of the SELFAUTO... variables (such a texmf.cnf file is
probably broken, but that may not be your problem, or within your
power to fix). This option makes
dvi2bitmap claim to be a different DVI-reading program which
is installed in the standard place. See Section 2.5.1 for discussion. The configuration script uses
the location of the xdvi program by default, but you can
override this by giving the full path to an alternative as an argument
to this option.Since this uses undocumented behaviour of the library (`use the source, Luke!'), you probably shouldn't enable it unless you have to.
The ./configure command without any options is
equivalent to ./configure --with-kpathsea --enable-png
--enable-mktexpk (meaning that kpathsea and PNG output will be
enabled if library support for them is found).
The program builds successfully on (at least):
The `version' column is the last version which was actually tested on that platform. Reports of compilations on other platform/compiler combinations gratefully received.
Platform Version Compiler i686-pc-linux-gnu (RedHat 6.2) 0.9-6 egcs-2.91.66 powerpc-unknown-linux-gnu (Mac mklinux DR-0.3?) 0.9 egcs-2.90.25 980302 (egcs-1.0.2 prerelease) sparc-sun-solaris2.7 0.9 egcs-2.91.66 sparc-sun-solaris2.7 0.9 gcc 2.8.1 sparc-sun-solaris2.7 0.9-6 WorkShop Compilers 5.0 98/12/15 C++ 5.0 alpha-dec-osf4.0f 0.9-6 Compaq C++ V6.2-024 for Digital UNIX V4.0F
It should be written in standards-conforming C++, so if it doesn't build then (1) it's not as conformant as I think it is (in which case please tell me), (2) your compiler is not as conformant as you think it is (in which case please don't tell me), or (3) you need to invoke some magic to get the compiler to be conformant (in which case tell me, if there's something I can do in the autoconfigure script).
You can override the C++ compiler the configure script will choose by
setting the environment variable CXX, either via
or% CXX=cxx ./configure
depending on your shell.% env CXX=cxx ./configure
kpathsea libraryNot all TEX distributions install the kpathsea library,
even though they install applications built with it, and the
texmf.cnf configuration file which controls it.
If the library does not appear to be in your distribution, then you
can obtain and build it yourself. The library is distributed as part
of the web2c (Unix TEX source) distribution, which you can
find at <ftp://ftp.tug.org/tex/web2c.tar.gz>, or mirrored on
CTAN sites (for example at <http://www.tex.ac.uk> in
directory systems/web2c).
Take a copy of the
library (this is a big distribution), and unpack it. Go into the
kpathsea directory and do the usual
`./configure; make; make install' routine. With (some?)
older distributions of the library this appeared not to work, and you
had to go to the parent of the kpathsea directory, delete the
web2c directory (which is the bulk of the distribution), then configure
and build it as usual, ignoring the warnings about the missing main
texmf tree.
If you are on a Starlink node, then you
should be able to use the usual mk script. Define the
environment variables INSTALL and SYSTEM as usual.
SYSTEM can be any one of the Starlink-supported platforms
ix86_Linux, alpha_OSF1 or sun4_Solaris. Then
give the commands
% ./mk build % ./mk install
This build configures support for GIFs, plus support for the
kpathsea library if that library is present on the system (it
is not distributed with this package and not present by default on all
project machines).
There are some issues involved in creating, and hence in
installing, an export_run distribution. Part of the
configuration of dvi2bitmap involves establishing the location,
on the build system, of font-building scripts and TeX configuration
files. However, the point of the export_run distributions is
that it should run on systems other than the build system. We
deal with this by (a) configuring dvi2bitmap to use a custom
font-building script, which is distributed and installed with the
package, and which is simply an interface to whichever of the real
font-builders is available on the target system, and (b) configuring
it with --disable-texmfcnf. The former should be OK as long as
one of mktexpk and MakeTeXPK is in the path after
installation. The latter, however will cause a problem if
kpathsea is enabled (which may or may not be the case for the
export_run system), since this will probably fail unless
the environment variable TEXMFCNF is defined (see
kpsewhich cnf texmf.cnf). You can see what features are enabled
with the command dvi2bitmap -V.
Bugs:
getopts as soon as I get the chance.To report bugs, please send to norman@astro.gla.ac.uk a
brief description of the problem;
a minimal TEX file which reproduces it;
some indication of the machine you're running on (uname -a is good);
and the output of dvi2bitmap -V, which shows the options you
have enabled.
Things I'd like to do sometime:
Bright ideas, fixes and (especially) implementations, cheerfully received.
In the .../extras directory of the
distribution is a script img-eqlist.pl, which transforms a
file of LaTeX fragments into a LaTeX file, keeping track of
filenames, and avoiding generating duplicate bitmaps for duplicated maths.
CTAN, the Comprehensive TEX Archive Network, is the
repository of TEX and LaTEX documentation. The archive is
mirrored in numerous places, but the UK node is at
<http://www.tex.ac.uk>.
DVItype and PKtoPX are two programs Donald Knuth intended
as model DVI and PK file
readers, and as containers for the canonical documentation of the DVI
and PK file formats. They might be available as part of your TEX
distribution, but are also available on CTAN, in
/tex-archive/systems/knuth/texware/dvitype.web
and
/tex-archive/systems/knuth/pxl/pktopx.web.
The DVI Driver Standard, Level 0 is
available on CTAN, in directory
/tex-archive/dviware/driv-standard.
This incorporates sections of the DVItype documentation.
This program claims to conform to this standard: if it doesn't, please
let me know.
Thanks for bug reports and other suggestions to Eitan Gurari
(heroic tester), Oliver Schurr and Oleg Bartunov (oleg@sai.msu.su).
The real issue here (for me at least) is rendering
equations within an HTML document. There are several tools available
which can do that with different trade-offs. The most popular method
is to write the equations in a LaTEX document, process it, and then hoik
the equations out of the resulting DVI file somehow (typically using
dvips and a postscript to gif converter), and display them
on the web as gifs. The big disadvantage with this is that you get an
awful lot of gifs, and the conversion is rather inefficient.
All this hassle should become irrelevant once we get browsers which can render MathML directly.
There are reviews of the problems, and some of the tools, in articles Maths Typesetting for the Internet, and Comparative Review of World-Wide-Web Mathematics Renderers.
LaTeX2HTML is the granddaddy of these translators - it parses the LaTEX using Perl, and spits out HTML, turning maths into gifs. It's very robust by now.
John Walker's textogif is a Perl program which orchestrates the various tools to do the conversion via postscript, once you've generated the DVI file. It works, but it's terribly slow, which was the motivation for this program.
TeX4ht (TEX for Hypertext) uses TEX's own parser, but still produces equations as gifs. TeX4ht can also emit MathML from LaTeX. The TeX4ht documentation has a useful collection of resources. There's an alternative location for TeX4ht at TUG.
tth: TeX to HTML translator
(manual). tth translates LaTEX maths directly to HTML,
with remarkable success and astonishing speed, and with good failure
strategies. It works
very sweetly, but (a) requires you to tweak your browser to have it
map the symbol font appropriately, and (b) the resulting HTML can't be
printed legibly. From the same source is
TtHMML, which translates (La)TEX to HTML plus MathML.
nDVI is a DVI viewer plugin for Unix Netscape. This addresses the problem at the client end.
A quite different approach is to use a different markup for maths, possibly requiring specialised client software. These other notations typically use semantic markup - expressing the structure of the maths. At first sight, this seems preferable to LaTEX's presentational markup, but its weaknesses for authoring are exposed (I feel) when you realise that maths is not as closed and unambiguous a language as computer scientists feel it ought to be. Semantic markup's strength is in interfaces with computer algebra systems, and databases - Abramowitz and Stegun would be ideal in this form! The major dislocation between the two approaches is what makes conversion from presentational to semantic markup so easy. In passing, I'll note that MathML has both a presentational and a semantic variant.
MINSE uses a server to render maths into gifs on the fly. It seems to work rather nicely, but works with its own semantic maths notation.
There is (was?) a project called Euromath, which includes a structured SGML editor. This project included a converter which could transform LaTEX to Euromath SGML.
OpenMath might be a successor to Euromath. It's an EC Esprit project which `proposes to develop standards for the semantically-rich representation of mathematics'.
GELLMU is a LaTEX-like markup language, intended to be easy to convert to SGML. Specifically, it is intended to support maths (and hence conversion to MathML) well.
The following are specifically concerned with maths in SGML, using either MathML or other maths DTD fragments.
WebEQ is a suite of Java programs which implement MathML. It's commercial.
TeXML is a gadget from IBM which converts XML to TEX via a DTD fragment. You transform your XML to an equivalent document marked up in TeXML, which you then separately transform to TEX.
EzMath is a Dave Raggett proposal for producing maths on the web. It uses yet another notation, and converts it to online form using a plugin (no printing, and Windows only, as of April 1999).
When producing this program, I became terribly confused about the
variety of dimensions which appear in DVI and PK files. Table 1
is a summary of the sizes which appear, for the benefit of anyone else
attempting a project like this. The reference [Dn] refers to
section `' of the webbed DVItype document and [Pn] to section `' of
the PktoPX document (see Section 5).
If you feel I have misunderstood something here, or got one of the conversion factors wrong (I hate these!), please correct me.
| Context | Description | See |
|---|---|---|
| DVI preamble | num, den: multiply a `DVI unit' by
 to obtain a length in units of
 | [D17] |
mag: DVI units are actually multiplied by
 | [D17] | |
| DVI font definition | d: a design size, in DVI units. The nominal size of the font. | [D18] |
s: a `fixed point' scale factor, range
 , scaling d (see note). | [D18] | |
| PK preamble | ds: the font design size in units of  points. | [P12] |
hppp, vppp: number of pixels per point, times
 (see note). | [P12] | |
| Character | tfmwidth: the width of the character (see note). | [D37], [P9] |
w, h: the width and height, in pixels, of the
character pixel map. | [P21] | |
hoff and voff: offset of the pixel map from the
reference point. | [P21] | |
dm, dx, dy: the pixel escapements.
dm in pixels, dx and dy in pixels times
(see note). | [P21] |
Sizes in TeX
s scales the design size, so that a font is actually used at
times its normal
size.hppp and vppp aren't used as sizes, but can be used
to check you have the right fonts by comparing resolution, etc..tfmwidth is the `physical' size of a character, and is the
only size that TEX uses in its calculations, and which the DVI
reader uses when working out how far to move the reference point when
it sets a character. This is defined in [P9] to be in units of
FIXes, where one FIX is times the design
size in points. [D37] describes how to multiply these widths by
scaling factors without overflowing.tfmwidth
is that the latter is a resolution-independent shift of the DVI
reference point, and the former is the PK file's recommendation of the
number of pixels the DVI processor should actually move. The DVI
processor keeps track of the two reference points, and readjusts the
pixel-based one when rounding errors move it too far from the
resolution-independent one. See [D89] and [D91]; also [D40].A few useful conversions are:
points. [P12]FIX is a physical size, of length
tfmwidth parameter is
in units of FIXes, so that the TFM width is a length of
tfmwidth fixes, which is equal to 
points.
points, `px' for pixels, and 
for Knuth's
deci-micron, or ,
Fixed a character-handling bug. Oleg Bartunov (oleg@sai.msu.su)
identified an error in the handling of some of the opcodes in the DVI
file, which meant that only 7-bit fonts were being set correctly (how
parochial of me!). He also sent me the fix - many thanks to him.
Also made a change to the options of the configuration script,
turning --enable-kpathsea back to
--with-kpathsea, which is more sensible, in retrospect (I
think the processing of this was rather garbled in the previous version).
Added some functionality, but more importantly corrected two nasty font bugs.
-bp, to set initial bitmap size based on
paper sizes and -Qp to list the sizes available. Added option
-PC to turn off cropping, which is useful if you want output of
a certain size.No functionality change. The only difference from release 0.9-4 is
to the packaging for Starlink nodes (added a working export_run
target).
No significant added functionality to the main program, but:
-QG and -Qg options (see item `-Q...').test directory, and test script, which aims to give
useful advice about setting DVI2BITMAP_PK_PATH if that turns
out to be necessary.make test' target in the Makefile.-q turns off warnings, but not errors (was
rather inconsistent before), and -qq turns off errors, too.Bugfix release. The program was crashing on Suns, when built with gcc 2.8.1. I'm not sure I found any underlying problem, but I fixed something, which stopped it crashing for me (Mmmm...).
This release adds a script img-eqlist.pl, to transform
a file of LaTeX maths fragments into a LaTeX file, keeping track of
filenames, and avoiding generating duplicate bitmaps for duplicated
maths. See Section 4.
No big changes, but a sufficiently significant change in the functionality to require a new minor version, rather than just a new release number.
-Q options (see item `-Q...') now write
their output lines (to stdout)
prefixed by the option letters, so that the output of -Qf now
consists of lines starting `Qf '. This makes it easier to
disentangle the output if several of these options are present - it
was added when option -Qb was added - but means that any
scripts parsing the previous version's output would break.-Rf and -Rb added (see item `-R[fb] int,int,int'), to set the foreground and
background colours on the command line, rather than just using the
foreground special. This is still a
bit rudimentary, as it can be done only once, for the whole document.Added support for palettised PNG output. This was intended to allow me to support full transparency on PNGs, but the particular case which is appropriate for this seems to be very poorly supported in PNG viewers, so, although I believe the output to be correct, you can't see the benefit in most cases.
That made it easy to support changing the foreground and background colours for output text, so I did that as an encore.
Added the `strut' special.
Version number fiddling: this is still beta software, and as such shouldn't be sent out with a major version number of 1. Also, I'd been updating the `release number' (after the hyphen) with new releases - this is incorrect, as this should indicate only bug-fixing or documentation changes, rather than changes in functionality. I've therefore rationalised the version numbering, and changed history to the extent of modifying the notes in this ReleaseNotes section. This shouldn't cause significant confusion, as this package has up to now only been circulated internally.
Added support for PNG graphics, using the libpng library, if it's installed.
The Metafont mode used for building fonts is now configurable at
runtime; the default is configurable at configuration time; and
default default (!) mode and resolution now properly match, so that
you no longer have to give the -r option every single time.
The manpage source was brought up to date.
The -f option was split into the -fp, -fm,
-fg and -fG options.
The --enable-fontgen flag was added to the
configuration script.
Various clarifications to the documentation.
Assorted tidy-ups to get it to satisfy -Wall on a wider
range of platforms.
Added support to allow the program to lie about its name. For a discussion of the need for this, see Section 2.5.1.
Missing fonts are now generated by the program, and the
TEXMFCNF variable is now set automatically (unless that
behaviour is suppressed at configuration time).
Support for more sophisticated cropping.
The DVI2BITMAP_PK_PATH environment variable now accepts a
colon-separated list of directories to search. The font searching
algorithm which uses that variable now does the font-size rounding
calculation properly, and will additionally search for fonts within
0.2% of the target size, as required by the DVI Driver
Standard.
The kpathsea font searching mechanism is still the preferred way of finding fonts, but since many folk don't have, or don't want to obtain, access to the library, I've made the simple font-searching algorithm marginally more sophisticated, as described above.
No significant changes to functionality, but a couple of documentation and packaging improvements.
Norman Gray, 12 January 2001
Took opportunity of a bug-fix release of the software to make miscellaneous minor edits to the documentation.
Added `version' column to table, noting which version was actually tested.
Updated nDVI URL
Norman Gray, 8 November 2000
Minor changes to the configuration options, plus a couple of documentation tidyups.
Mentioned that the -gp option also debugs kpathsea.
Changed the disable-kpathsea configuration option to without-kpathsea (see also release notes for this version).
Norman Gray, 27 June 2000
Added -bp, -PC, -Qp options, and corrected bugs which caused fonts to be generated at the wrong sizes, and to be spaced incorrectly.
Added -bp, -Qp, -PC
Added -PC
Norman Gray, 23 June 2000
Adjustments to distribution - no functionality change.
Added a note discussing the export_run
distribution bundle, and possible problems with it.
Norman Gray, 21 June 2000
Mostly clarifying and amplifying explanations.
Added documentation of -QG and -Qg
Added discussion of the `make test' script, and clarified (I hope) description of how to set DVI2BITMAP_PK_PATH.
Norman Gray, 16 June 2000
Explained how to set DVI2BITMAP_PK_PATH automatically.
Added description of setting DVI2BITMAP_PK_PATH automatically.
Added discussion of the `make test' script, and clarified (I hope) description of how to set DVI2BITMAP_PK_PATH.
Norman Gray, 12 June 2000
Bugfix release.
Norman Gray, 11 June 2000
Minor functionality changes, but significant interface changes, so new version.
Added -Qb, and add extra field to output, so that output from different -Q options can be separated out.
Add -Rf, -Rb options, to set colours on the command line.
Norman Gray, 8 June 2000
Documented changes to list of specials (foreground and background colours, and strut).
Added -PB and -PT
Added foreground and background specials, to set foreground and background colours.
Added strut special.
Norman Gray, 12 May 2000
Described problems finding fonts.
Described potentially confusing interaction between enable-kpathsea and enable-fontgen configuration options.
Moved description of --enable-fontgen, and new default setting.
Added bugreport address
Norman Gray, 5 May 2000
New release. Documentation tidyups. Mentioned new support for PNG graphics.
Clarified the -p, -l and -pp options. Changed -Q into -qq, and -L into -Qf.
Mentioned PNG option
Added documentation of imageformat special.
Described --enable-fontgen. Rename of kpathsea option to --disable-kpathsea. Addition of --enable-png.
kpathsea libraryImproved instructions on getting the kpathsea library source.
Norman Gray, 18 September 1999
Add --enable-fake-progname.
Mentioned --enable-fake-progname
Mentioned --enable-fake-progname
Norman Gray, 13 September 1999
Added page-selection features, and documented them.
Added documentation of -p, -l, -pp options. Note that the old -l and -L options have changed into the new -L and -LL options.
Added a discussion of the foibles of the texmf.cnf configuration file when it comes to finding fonts.
Norman Gray, 6 September 1999
Assorted changes, to describe significant new functionality.
Added documentation of -c and -C options
Rewritten to cover new special commands, particularly support for cropping.
Largely rewrote the configuration instructions, in an attempt to make them clearer.
Norman Gray, 5 July 1999
Altered documentation of font-searching, to match new functionality.
Added a description of my usage model, to help make things a little clearer.
Described new functionality for environment variable.
Norman Gray, 24 June 1999
Slight restructuring to make it easier to find the instructions on generating fonts. Fixed a couple of typos.
Renamed this section from vague `environment', and moved description of font generation from examples.
Norman Gray, 19 June 1999
Added kpathsea support, and appendix on TeX dimensions.
Added instructions on configuring in support for the kpathsea library
Norman Gray, 14 June 1999
First public release
Norman Gray, 14 June 1999
Initial version
Index of IDs in this document. Exported IDs indicated like this.
<subsect id=usage.options>2.1 Options
<dt id=usage.options.fp>item `-fp font-path'
<dt id=usage.options.fm>item `-fm mode'
<dt id=usage.options.g>item `-g(d|p|r|i|b|m|g)'
<dt id=usage.options.q>item `-Q...'
<dt id=usage.options.r>item `-R[fb] int,int,int'
<subsect id=usage.special>2.2 DVI specials
<dt id=usage.special.opf>item `outputfile <filename>'
<dt id=usage.special.fg>item `default foreground|background red green
blue '
<subsect id=usage.exit>2.3 Exit value
<subsect id=usage.examples>2.4 Examples
<subsect id=usage.fonts>2.5 Finding and generating fonts
<subsubsect id=usage.fonts.finding>2.5.1 Finding fonts
<subsect id=install.nonstarlink>3.1 General installation and configuration
<dt id=conf.enable-fontgen>item `--enable-fontgen
'
<subsubsect id=install.web2c>3.1.1 Obtaining the kpathsea library
<subsect id=install.starlink>3.2 Starlink nodes
<subsect id=sgml.maths.latex>A.1 LaTEX maths within HTML
<subsect id=sgml.maths.other>A.2 Other approaches to maths
<table id=tsizes>Table 1
<subsect id=rn-0.9-6>C.1 Release 0.9-6
<subsect id=rn-0.9-5>C.2 Release 0.9-5
<subsect id=rn-0.9-4>C.3 Release 0.9-4
<subsect id=rn-0.9-3>C.4 Release 0.9-3
<subsect id=rn-0.9-2>C.5 Release 0.9-2
<subsect id=rn-0.9>C.6 Release 0.9
<subsect id=rn-0.8>C.7 Release 0.8
<subsect id=rn-0.7>C.8 Release 0.7
<subsect id=rn-0.6>C.9 Release 0.6
<subsect id=rn-0.5>C.10 Release 0.5
<subsect id=rn-0.4>C.11 Release 0.4
<subsect id=rn-0.3>C.12 Release 0.3