dvi2bitmap

Version @VERSION@, @RELEASEDATE@

dvi2bitmap is a utility to convert TeX DVI files directly to bitmaps,
without going through the complicated (and slow!) route of conversion
via PostScript and PNM. The prime motivation for this is to prepare
mathematical equations for inclusion in HTML files, but there are
plenty of uses beyond that. It uses the same kpathsea font-searching
library as other TeX programs, as long as you have the
appropriate library installed.

Note: this code has not been much changed since around 2005, with main
development having tailed off, as being more-or-less feature complete,
from 2003. It's had a few bugfixes since then, and there are some
possibilities for future projects in the file TODO.

Features:

• Written in C++.

• The program is a wrapper for libdvi2bitmap, a library which abstracts
  DVI and PK files, Bitmaps, and various other objects supporting
  these.

• Supports GIF, XBM, XPM bitmaps as output, plus PNG if libpng is
  installed.

• Can read DVI files from a non-seekable stream such as a pipe.

• Internally constructed bitmap is expandable.

• Integrated with the kpathsea path-searching algorithm, as used by other
  TeX and DVI programs. It is not, however, dependent on it, so it
  will still work happily if you don't have the library installed.
  Can use a pre-set search path, or scripts, to find fonts instead.

• Can generate fonts on the fly.

• Highly configurable, and very fast. Designed for use in a batch
  production mode.

• Released under the GPL.

See http://purl.org/nxg/dist/dvi2bitmap

Configuring and building

To configure and build:

./configure
make
make install

Important ./configure options are

• --with-png=... : points to the libpng library

• --with-kpathsea=... : points to the kpathsea library, for finding
  TeX fonts; see the documentation for discussion

You can override the C++ compiler the configure script will choose by
setting the environment variable CXX, either via CXX=cxx ./configure' orenv CXX=cxx ./configure', depending on your shell. Choose the
install location with the argument --prefix.

Since this program uses standard' TeX fonts, but at resolutions appropriate for screens rather than paper, there is a certain fuss involved in generating, and after that, finding, these fonts. If you have thekpathsea' library installed, then this should Just Work.
Failing that, you might have to set an environment variable. See the
section of the manual entitled `Finding fonts' for some discussion of
this. As well, it's a good idea to give the command

(cd test; make)

after you've built the distribution. As well as testing the program,
this attempts to give you some advice about what you need to do on
your particular system to tell dvi2bitmap where its fonts are.

The program can work with the kpathsea library. This is the same
path-searching library which several TeX implementations use to find
fonts (and more). If you wish to use this (you should, if you can),
then give the option `--with-kpathsea' to the configure command, again
optionally specifying a path, and if the library is installed on your
machine, the program will use it. To build the library, see the
discussion on 'building kpathsea' below.

If you want it to be able to generate GIFs, then give the configure
option --enable-gif'. Starting in 2005, this is enabled by default, since the Unisys patents appear to have expired in 2004. You can disable the ability to generate GIFs (probably a good plan, if you have the PNG library available) with the option--disable-gif'.

If you want it to be able to generate PNG files (much better, since
they're free of the GIF copyright problems), then give the configure
option --with-png'; if you don't have libpng in the default places (typically /usr/lib or /usr/local/lib), then instead use--with-png=/path/to/png', where the specified path is that to the
directory which contains the png include/ and lib/ directories. This
will check you have the libpng library and headers somewhere the
compilers can find them, and build in support if it finds them. The
PNG library is not distributed with this utility: you can find it at
http://www.libpng.org/pub/png/.

The program builds successfully on (at least) the following
machine/compiler combinations. 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).

powerpc-apple-darwin6.6 (MacOS X, 10.2.6)
    g++ 3.1 20020420 (prerelease)

sun-sparc-solaris2.9
    CXX=CC: Sun WorkShop 6 update 2 C++ 5.3 2001/05/15

alphaev67-dec-osf5.1
    CXX=cxx: Compaq C++ V6.5-014

i686-pc-linux-gnu (RedHat 7.3)
    g++ 2.96

Building kpathsea

To build the kpathsea library (presuming it's not available in your
TeX distribution), you should start from a Subversion checkout.
You can check out the entire tree
(with the command 'svn co svn://tug.org/texlive/trunk/Build/source')
but that takes a long while.
Or you can check out just the required bits:

% svn co svn://tug.org/texlive/trunk/Build/source/m4
% svn export svn://tug.org/texlive/trunk/Build/source/version.ac
% svn co svn://tug.org/texlive/trunk/Build/source/texk/am texk/am
% svn co svn://tug.org/texlive/trunk/Build/source/texk/kpathsea texk/kpathsea
% svn co svn://tug.org/texlive/trunk/Build/source/texk/tests/texmf texk/tests/texmf
% cd texk/kpathsea

Then build:

% autoreconf --install --symlink
% ./configure
% make
% make check
% make install

Alternatively, snarf a copy of the base tree from eg
http://www.tex.ac.uk/tex-archive/graphics/metapost/base.zip, unpack
it, cd to base/source/texk/kpathsea, and build as above.

Font-string templates

Several things which can be configured -- either at ./configure time
or in the config.h file, if you have to edit that explicitly -- are
specified as being in the form of a `font string
template'. This is a printf-like string which has %? specifiers
replaced by font parameters, according to the following scheme:
%M = mode (eg. ibmvga)
%f = font name (eg. cmr10)
%d = dpi (eg. 330)
%b = base dpi (eg. 110)
%m = magnification (eg. 3)
%% = %

This also applies to the DVI2BITMAP_PK_PATH environment variable,
which may be used to point to the PK paths generated by dvi2bitmap.

This applies to the font-generation script and font-search scripts.

Documentation

See directory doc/ -- there are fuller installation instructions
there. Full library documentation in directory doc_libdvi2bitmap/.
There's also a man-page in dvi2bitmap.1, but this is not
necessarily as up-to-date as the main documentation.

Author

Norman Gray http://nxg.me.uk
See also the other contributors in the file AUTHORS.

Copyright

Copyright 1999--2004, Council for the Central Laboratories of the Research Councils.
Copyright 2005--2017, Norman Gray.
Released under the terms of the GPLv2, a copy of which is included in the file LICENCE.