Version @, @

dvi2bitmap is a utility to convert Te\-X D\-V\-I files directly to bitmaps, without going through the complicated (and slow!) route of conversion via Post\-Script and P\-N\-M. The prime motivation for this is to prepare mathematical equations for inclusion in H\-T\-M\-L files, but there are plenty of uses beyond that. It uses the same kpathsea font-\/searching library as other Te\-X programs, again as long as you have the appropriate library installed.

Features\-:
\begin{DoxyItemize}
\item Written in C++.
\item The program is a wrapper for libdvi2bitmap, a library which abstracts D\-V\-I and P\-K files, Bitmaps, and various other objects supporting these.
\item Supports G\-I\-F, X\-B\-M, X\-P\-M bitmaps as output, plus P\-N\-G if libpng is installed.
\item Can read D\-V\-I files from a non-\/seekable stream such as a pipe.
\item Internally constructed bitmap is expandable.
\item Integrated with the kpathsea path-\/searching algorithm, as used by other Te\-X and D\-V\-I 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.
\item Can generate fonts on the fly.
\item Highly configurable, and very fast. Designed for use in a batch production mode.
\item Released under the G\-P\-L.
\end{DoxyItemize}

See \href{http://purl.org/nxg/dist/dvi2bitmap}{\tt http\-://purl.\-org/nxg/dist/dvi2bitmap}

\subsection*{Configuring and building }

To configure and build\-: \begin{DoxyVerb}./configure
make
make install
\end{DoxyVerb}


Important ./configure options are
\begin{DoxyItemize}
\item --with-\/png=... \-: points to the libpng library
\item --with-\/kpathsea=... \-: points to the kpathsea library, for finding Te\-X fonts; see the documentation for discussion
\end{DoxyItemize}

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

Since this program uses `standard' Te\-X 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 the `kpathsea' 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 \begin{DoxyVerb}(cd test; make)
\end{DoxyVerb}


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 Te\-X 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 G\-I\-Fs, 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 G\-I\-Fs (probably a good plan, if you have the P\-N\-G library available) with the option `--disable-\/gif'.

If you want it to be able to generate P\-N\-G files (much better, since they're free of the G\-I\-F 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 P\-N\-G library is not distributed with this utility\-: you can find it at \href{http://www.libpng.org/pub/png/}{\tt 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). \begin{DoxyVerb}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
\end{DoxyVerb}


\subsection*{Building kpathsea }

To build the kpathsea library (presuming it's not available in your Te\-X 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 {\itshape 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 \href{http://www.tex.ac.uk/tex-archive/graphics/metapost/base.zip}{\tt http\-://www.\-tex.\-ac.\-uk/tex-\/archive/graphics/metapost/base.\-zip}, unpack it, cd to base/source/texk/kpathsea, and build as above.

\subsection*{Font-\/string templates }

Several things which can be configured -- either at ./configure time or in the \hyperlink{config_8h}{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 D\-V\-I2\-B\-I\-T\-M\-A\-P\-\_\-\-P\-K\-\_\-\-P\-A\-T\-H environment variable, which may be used to point to the P\-K paths generated by dvi2bitmap.

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

\subsection*{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.

\subsection*{Author }

Norman Gray \href{http://nxg.me.uk}{\tt http\-://nxg.\-me.\-uk} See also the other contributors in the file A\-U\-T\-H\-O\-R\-S.

\subsection*{Copyright }

Copyright 1999--2004, Council for the Central Laboratories of the Research Councils. Copyright 2005--2015, Norman Gray. Released under the terms of the G\-P\-Lv2, a copy of which is included in the file L\-I\-C\-E\-N\-C\-E. 