path: root/dviware/dvi2bitmap/dvi2bitmap.1.in

.TH DVI2BITMAP 1 "@RELEASEDATE@"
.SH NAME
dvi2bitmap
.SH SYNOPSIS
.B dvi2bitmap
[flags] dvi-file
.SH DESCRIPTION
dvi2bitmap processes a DVI file produced by the TeX typesetting
system, converting each page to a single bitmap.
.PP
This man-page documents 
.I dvi2bitmap
version
.I "@VERSION@"
.PP
This program is intended to conform to the DVI processing standard.
.PP
The principal documentation for this package is in the HTML document
distributed with it.  This man-page may differ from the documentation
there.
.PP
The 
.I dvi-file
argument is the name of a DVI file to be converted to a bitmap.
dvi2bitmap looks for the file both with and without the default
extension
.I .dvi
.PP
You may also read the DVI file from the standard input by giving the
DVI file as 
.I "-"
, thus 
    \f(CRcat myfile.dvi | dvi2bitmap -\fP
.br
is an alternative way of reading the file (rather pointless in this
case, but it shows the principle).
For more arcane purposes, the DVI file may also be specified as 
.I <osfile>dvi-file
(which is entirely equivalent) or 
.I <osfd>integer
, where the given integer specifies an open file descriptor;
specifying 
.I "-"
as the input file is equivalent to 
.I <osfd>0
.SS OPTIONS
.PP
Various of the options below have common syntax features.
.TP
.I [keyword-list]
This indicates a sequence of
.I keyword=value
pairs, separated by commas.  Not all keywords necessarily have a
value.
.TP
.I [boolean]
This can be `yes', `true' or `on' indicating
.I true
, or `no', `false' or `off' indicating
.I false.
.PP
The options are as follows:
.TP
.I "-c, --crop=[keyword-list]"
.\" .I "\-c[edge] dimen, \-C[edge] dimen"
The 
.I "--crop"
option allows you to control how the
generated bitmaps are cropped before they are written.  The keywords
are `left', `right', `top', 
`bottom' and `all', and the value in each case is the number of pixels
to leave as a margin.  If the
keywords `relative' (default) or `absolute' are present, they refer to
all of the keywords following: if the crop is specified as `relative',
then the values specify the number of pixels to leave around the
blackened pixels of the text; if the crop is `absolute', then it
specifies the position of the crop (in pixels) from the left or top
edge of the `page'.  The specification 
.I "--crop=absolute,all=dimen"
, which would set all
the crops to the same position, is silly, and so is forbidden.
.IP
You should specify the crop option
.I after
the
.I --magnification
option, to ensure that the conversion from points to pixels takes
account of that.  The conversion currently takes no account of any
magnification in the DVI file, nor of the
.I --scaledown
option.  This is less of a burden than it might seem, since in the
presence of magnifications and resolutions, determining the crop
margin size is more of a matter of trial-and-error than you might expect.
.IP
See below for TeX 
.I "\especial"
commands which set this within the TeX file.
.TP
.I "-F, --font-search=[keyword-list]"
Specifies how 
.I dvi2bitmap
is to find the fonts it needs.  Keywords are as follows:
.IP
.I path[=list]
: use the given colon-separated list of filesystem paths to search for PK
fonts, or enable using the default path, if the list is
missing.  The default path is given by the environment variable
.I DVI2BITMAP_PK_PATH.
See also the discussion of font searching below.
.IP
.I kpathsea
: enable using the
.I kpathsea
library to find fonts.  If the program was not built against the
.I kpathsea
library, this option has no effect.
.IP
.I command[=script]
: enable using the given script to
find fonts.  If the argument is missing, this enables using the script
configured into the program at compile-time.  This script is any
program which will search the filesystem and produce a single line on
output, giving the full path to the specified font.  For example, this
might be given as
    \f(CR--font-search=command="kpsewhich pk %f.%dpk"\fP
.br
to run the
.I kpsewhich
program.  The command name is a font-string
template, as described below.
.IP
If the program does not find a font using whichever methods have
been enabled then, following the pattern of
.I dvips
and other DVIware, it writes a file
.I missfont.log
in the current directory, containing commands which you can use to generate
the fonts immediately or later.
.IP
.I none
: disable all font-searching.  The result is that
only the
.I missfont.log
file is written.
.IP
Each of the keywords can be prefixed by `no' to turn off the
corresponding option -- thus
.I --font-search=nopath,nokpathsea,nocommand
has the same effect as
.I --font-search=none
.TP
.I "-G, --font-gen=[[boolean]|command[=script]]"
Switch automatic generation of fonts off and on.
If 
.I --font-gen=command
is given, then the command specified at compile time is used to
generate fonts.  If, further, a font-generation script is specified, then it
will be used instead of the default.  The specified script is a
font-string template, as described below.
The default for automatic font generation is set at compile time.
.TP
.I "-g, --debug=[spec]"
Switch on debugging.  The
.I [spec]
is a list of letters indicating what to debug, as follows.
You may trace DVI file parsing
(`d'), PK file parsing (`p'), font rasterdata parsing (`r'), input
(`i'), bitmap generation (`b') or the main program (`m').  Adding an
extra `g' increases still further the amount of debugging code.  The
debugging information may be uninformative or unintelligible; it might
even crash the program (mention that to me).
.TP
.I "-h, --height=size; -w, --width=size"
Specify the height and width of the canvas on which the output
bitmap is painted.  The program tries to make an estimate of this
based on information within the DVI file, but it can't efficiently get
all the information it needs, so sometimes the estimate is wrong.  If
you get a warning message like 
.I "Warning: p.12: bitmap too big: occupies (1183,1072)...(4134,6255). Requested 4100x6200"
then 
you'll need to specify a bitmap size.  The numbers
.I "(1183,1072)...(4134,6255)"
are the coordinates of the top-left and
bottom-right of the bitmap: in this case 
.I "--height=6300 --width=4200"
would suffice.  At some point, I'd like to make the bitmap
`expandable', obviating the need for these options.
.TP
.I "--help"
Display simple help for the options on stderr, and exit.
.TP
.I "-l, --end-page"
See option 
.I "--start-page"
.TP
.I "-M, --font-mode=[mode]"
Set the MetaFont mode which is used for generating font files.  The
default is 
.I "ibmvga."
If you set this, you will probably have to set the resolution to a consistent
number.
.TP
.I "-m, --magnification=[number]"
The TeX magnification parameter which is used when processing the DVI
file. It is a float, with 1.0 corresponding to no magnification (the
default).  This interacts with the resolution as follows: if you
specify a resolution of 100, and a magnification of 2, then
.I dvi2bitmap
will search for PK files at 200 dpi.
.TP
.I "-n, --nodvi"
Do not actually process the DVI file, but read the DVI pre- and
postamble.  Useful in conjunction with the 
.I "--query"
options.  If this option is present, then the program returns non-zero
if any fonts were missing.  The 
.I "-n"
is for brevity and consistency with other tools -- the behaviour can
be alternatively specified as
.I "--process=nodvi"
.TP
.I "-o, --output=[filename-pattern]"
Choose the output filename pattern.  If there is a 
.I "%d"
string within the pattern, then this pattern will be used for each
output file name, with the 
.I "%d"
replaced by the page number.  If there is no such string, then this
will be taken to be the name of the 
.I first
page output, after which the filename pattern will revert to the default.
This can be overridden on a per-page basis by a TeX
.I "\especial"
embedded in the DVI file (see below).  If there is no 
file extension, or if it does not match the output type, a suitable file
extension will be added.
.TP
.I --pipe
Indicates that the dvi-file argument is a non-seekable file, such as
a named or unnamed pipe.  This is automatically the case if you
specify the DVI file as stdin, "-".
.TP
.I "-p, --start-page=num"
.TP
.I "-l, --end-page=num"
.TP
.I "-P, --page-range=[spec]"
These select page ranges, using a slight extension of the notation
used by 
.I "dvips"
(and the same option letters, except that 
.I dvips
uses 
.I -pp
instead of
.I -P
).
.IP
The
.I "--start-page=snum"
and
.I "--end-page=enum"
options take single page numbers; if
either of these is given, then the program will process pages from
page 
.I "snum"
to page 
.I "enum"
, with the defaults being the
corresponding extremes.  The 
.I "[spec]"
consists of a
comma-separated sequence of page numbers and ranges (
.I "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 '\f(CR=\fP' or '\f(CR:n:\fP'.  In the former case, DVI page
numbers are used rather than the TeX
.I "\ecount0"
register; in the latter case, the program examines the 
.I "\ecountn"
register rather than the default 
.I "\ecount0"
.IP
You can specify both of these prefixes one or more times, but you
cannot mix the 
.I "--start-page"
and 
.I "--end-page"
options with the 
.I "--page-range"
option.  The program will respect only the last 
.I "--start-page"
and
.I "--end-page"
options, but the 
.I "--page-range"
options are cumulative.  There
may be no spaces in the 
.I "pagelist."
The page numbers may be negative.
.IP
Examples:
    \f(CRdvi2bitmap \--page-range=3,6\-10 ...\fP
.br
processes only the specified pages, and
    \f(CRdvi2bitmap \--page-range=:2:1 ...\fP
.br
processes only pages where
.I "\ecount2"
was 1.
.TP
.I "-Q, --query=[keyword-list]"
Query various things.  The available possibilities are as
follows.  The results of each of the queries is printed on a line by
itself, prefixed by a `Q', the keyword and a space, so that, for
example, each of the lines produced by the
.I "--query=missing-fonts"
option would start
    \f(CRQmissing-fonts cmbx10 110 ...\fP
.IP
Some of these options (
.I --query=missing-fonts
and
.I --query=missing-fontgen
) are probably most
useful with the
.I "\-n"
or
.I --process=options
options, to investigate a DVI file before processing.  Others (
.I --query=types
and 
.I --query=paper
) are probably useful only
with
.I --process=options.
The option
.I "--query=bitmaps"
is only useful if you do actually generate bitmaps.
For consistency (and so you don't have to remember which
ones do which), the appropriate
.I --process
option is 
.I not
implied in any of them, and you have to give it explicitly.
.TP
.I --query=bitmaps
Prints on stdout a line for each bitmap it generates, giving the
filename, horizontal size, and vertical size, in pixels.  This will
also report the position of any `mark' in the bitmap; see special `mark'
below.
.TP
.I "-Qf, --query=missing-fonts"
Show missing fonts.
The program writes on standard output one line per missing font,
starting with
.I "Qf"
or
.I "Qmissing-fonts"
(depending on which of the variants was given -- the shorter ones are
less mnemonic, but more convenient to parse in scripts), 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
.I "--query=missing-fontgen"
is more straightforward.
.TP
.I "-QF, --query=all-fonts"
As for
.I "--query=missing-fonts"
except that found fonts are also listed, all prefixed by
.I "Qall-fonts"
.TP
.I "-Qg, --query=missing-fontgen"
As for
.I "--query=missing-fonts"
, except that the output consists of the string
.I "Qmissing-fontgen"
followed by a 
.I "mktexpk"
or
.I "MakeTeXPK"
command which can be used to generate the font.
.TP
.I "-QG, --query=all-fontgen"
As for
.I --query=missing-fonts
, except that font-generation commands for found fonts are also
listed, prefixed by
.I "Qall-fontgen."
.IP
Only one of
.I --query=missing-fonts
,
.I --query=all-fonts
,
.I --query=missing-fontgen
and
.I --query=all-fontgen
should be specified -- if more than one appears, only the last
one is respected.  In each of these four cases, plus their short
forms, font-generation is automatically suppressed.  This is probably
what you want (it's not obvious why you're querying this otherwise),
but if you do not want this, then you can reenable font generation with 
.I --font-gen=true
.TP
.I --query=paper
Show the list of paper sizes which are predefined for the
.I --paper-size
option.
.TP
.I --query=types
List the output image formats which the program can generate, on
stdout, separated by whitespace.  The first output format is the default.
.TP
.I "-r, --resolution=[number]"
Specifies the output resolution, in pixels-per-inch.  This is used
when deciding which PK files to use. The default is 110, which matches
the default 
.I "ibmvga"
metafont mode.
.TP
.I "-R, --colours=[keyword-list], --colors=[keyword-list]"
Specifies the foreground or background colours, as RGB triples.  The
keywords are either
.I foreground
or
.I background
, and the values are a triple of integers separated by slashes, for example
.I "--colours=foreground=127/127/255"
The integers must be in the range [0,255], and can
be specified in decimal, octal or hex (for example
.I "127=0177=0x7f"
), or else the whole spec may be of the form
.I "#rrggbb"
, where `rr', `gg' and `bb' are each a pair of hex digits.
.TP
.I "-s, --scaledown=[number]"
Reduces the linear size of the output bitmap by a factor
.I "scaledown"
(default 1).
.TP
.I "-T, --output=type=[type]"
Choose the output format, which can be
.I "png"
,
.I "gif"
,
.I "xpm"
or
.I "xbm."
The program generates XBM bitmaps by 
default, and has simple support for XPM.  The GIF and PNG options may
not be available if they weren't selected when the program was configured.
.TP
.I "\-t, \-\-paper-size=papersize"
Set the initial size of the bitmap to be one of the paper sizes
returned by
.I "\-\-query=paper."
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
.I "\-\-process=nocrop"
option, to force the output bitmap to be a certain size.
.TP
.I "-v, --verbose=[normal|quiet|silent]"
Quiet mode suppresses some chatter, and silent mode suppresses
chatter, and does not display warnings or errors either.  Mode
`normal' is the default.
.TP
.I "-V, --version"
Display the version number and compilation options, and exit.
.TP
.I "-X, --process=[keyword-list]"
Specifies the processing to be done.
Keywords are as follows
.IP
.I dvi
and
.I nodvi
: enable or disable processing of the DVI file.  If disabled, we do
not require a DVI file to be present on the command line.  The 
.I nodvi
option is useful with some of the 
.I --query
options.
.IP
.I postamble
and
.I nopostamble
: enable or disable processing of the DVI postamble.  If dvi2bitmap is
called to invoke a non-seekable device such as a pipe, you should
disable processing of the postamble.  Disabling the postamble
processing is incompatible with the 
.I --query
options which examine the fonts in the file.  By default, both the
DVI body and the postamble are processed.
.IP
.I --process=options
: shorthand for 
.I --process=nopreamble,nodvi,nopostamble.  Only the options are examined
.IP
.I blur
and
.I noblur
: if true, 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
.I "--magnification"
option to magnify the DVI file, and then the
.I "--scale"
option to scale it back down to the correct size.
.IP
.I transparent
and
.I notransparent
: option 
.I transparent
makes the output bitmap have a transparent background, if
that's supported by the particular format you choose using option
.I "--output-type"
.IP
.I crop
and
.I nocrop
: if set, this specifies that you want the output bitmap to
be cropped.  This is true by default, so you'll most often use the
.I nocrop
to specify that you do not want the output cropped
(for example, if you're using the
.I "--paper-size"
option and want the output to stay the specified size).
.IP
By default, bitmaps are not blurred, are cropped, and are transparent
if possible.
.IP
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
.I 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.
.SH "DVI specials"
.I dvi2bitmap
recognises several DVI special commands, and emits a
warning if it finds any others.
.PP
The syntax of the special commands is 
  \f(CR\especial{dvi2bitmap <special-command>+ }\fP
.br
There may be one or more
.I "<special-command>"
sequences within a single special.
.PP
The
.I "<special-command>"
which the program recognises are:
.TP
.I "default"
Makes other special-commands in this same special affect
defaults.  See those commands for details.
.TP
.I "outputfile <filename>"
The output file used for the current page will be named
.I "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. 
.IP
If the
.I default
command has been given, then this instead specifies the default
filename pattern, and the `filename' should contain a single instance
of either
.I %d
or
.I #
; if there is no such instance, one will be implicitly added at the end.
.IP
The
.I %d
is precisely analogous to the behaviour of the
.I --output
option.  However it
is actually rather tricky to get an unadorned percent character into a
TeX special, unless you play catcode tricks, and this is why you may
alternatively include a
.I #
character to indicate where the
page number should go.  In fact, since it is also rather
tricky to get a single
.I #
character in a special, any immediately following
.I #
characters are ignored.  Thus the recommended way of specifying this
special is through something of the form
  \f(CR\especial{dvi2bitmap default outputfile myfile-#}\fP
using the
.I #
form, and letting the file extension be controlled by the output type
which is actually used.
.TP
.I "absolute"
Affects the
.I "crop"
command.
.TP
.I "crop <side> <dimen>"
Crop the bitmap on the current page so that the specified edge of
the bitmap is
.I "<dimen>"
points away from the bounding box of the blackened pixels.  
.I "<side>"
may be one of `left',
`right', `top', `bottom' or `all', referring to the corresponding
edge, or all four edges at once.  If the
.I "default"
command has been given in this special, then this pattern of cropping is
additionally made the default for subsequent pages.  If the
.I "absolute"
command has been given, then the crop position is set at
.I "<dimen>"
points from the appropriate edge of the `paper'.
.IP
The
.I "-c"
and
.I "-C"
command-line options have the effect of setting initial defaults.
In the absence of either of these, the initial crop is exactly at the
bounding box.
.TP
.I "default imageformat <format>"
Set the default image format, which should be one of the keywords
`xbm', `xpm', `gif', `png'.  This is equivalent to specifying the image
format through the 
.I --output-type
option.
.IP
The keyword is just 
.I "imageformat"
, but you must specify the
.I "default"
keyword when you
specify 
.I "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).
.TP
.I "default foreground|background red green blue"
.IP
Sets the (default) foreground and background colours for text.
This works, as long as you specify the colour change before any text
is output, since you can't, at present, change the colours after
that.  Specifically, you can't change the colours for a fragment of
text in the middle of a page; for this reason, and as with
.I imageformat
you should at present always include the 
.I 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, 
.I "127=0177=0x7f"
).
.TP
.I "strut <left> <right> <top> <bottom>"
.IP
This places a `strut' in the generated file.  Using the usual TeX
.I "\estrut"
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
.I "dvi2bitmap"
fits its tight bounding box to the blackened pixels
in the file, it knows nothing of the extra space you want.
.IP
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;
they are floats rather than integers, but they are rounded to pixels
before being applied to the growing bitmap.
.IP
If you wanted to set a page containing only the maths
.I "${}^\ecirc$"
(why, is another matter),
.I "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
.I "\especial{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.
.IP
A useful bit of TeX magic is:
  \f(CR{\ecatcode`p=12 \ecatcode`t=12 \egdef\eDB@PT#1pt{#1}}
   \egdef\eDBstrut{%
     \estrut\especial{dvi2bitmap strut 0 0 
       \eexpandafter\eDB@PT\ethe\eht\estrutbox
       \espace\eexpandafter\eDB@PT\ethe\edp\estrutbox}}\fP
.br
Once you've done that, the command 
.I "\eDBstrut"
will put an appropriate strut in the output.
.TP
.I mark
.IP
This sets a `mark' in the generated file, which is reported when
you specify 
.I "--query=bitmaps."
Normally, 
.I "--query=bitmaps"
writes out the horizontal and vertical size of the generated bitmap.
If use of this special has placed a `mark' in the bitmap, however,
then the
.I "--query"
option also reports the position of that
mark, as a position within the bitmap, such that the top-left corner
of the bitmap has coordinates (0,0).  For example, after
  \f(CR\enoindent\especial{dvi2bitmap mark}Hello\fP
.br
the command line
  \f(CRdvi2bitmap --query=bitmaps foo\fP
.br
might report
  \f(CRQbitmaps foo-page1.png 80 14 -1 10\fP
.br
indicating that the bitmap is 80 pixels wide by 14 high, and that the
reference point, after cropping, is at position (-1, 10).  The
`-1' is because the mark appears to the left of the `H' of `Hello' (and
the `H' probably has some negative offset), and the `10' indicates
that the baseline of this text is 10 pixels from the top of the
bitmap;  this latter information might be useful when working out how
to position this bitmap within a generated HTML file.
.IP
There's a certain amount of ambiguity in the specification of where
the `mark' position should be reported (it's the standard question of
whether the centre of a pixel has integer or half-integer
coordinates).  Also it's unclear what is the best interface to this
functionality, so it's possible that this might change in subsequent
versions.  The author welcomes comments.
.TP
.I "unit <u>"
.IP
The units in the `strut' and `crop' specials are by default in TeX
points.  You may switch to a different unit with the `unit' special.
The specifier `u' gives a unit name, which may be selected from the
set of units TeX knows about (`pt', `bp', `cm', and so on), plus
`pixels', and `dvi' to select DVI file units (usually the same as
`sp').  If the `default' qualifier is present, this setting applies
to subsequent special strings as well.
.PP
As an example, the pair of commands
  \f(CR\especial{dvi2bitmap default outputfile trial-#.gif unit pc crop all 5}
  \especial{dvi2bitmap absolute crop left 5}\fP
.br
will change the output filename pattern for the rest of the DVI file,
and set a 5pc margin round the bounding box.  The current page,
however, will have a left-hand crop five points in from the left hand
side.  Remember that TeX's origin is one inch from the left and the
top of the paper, and it is with respect to this origin that the
program reckons the absolute distances for the cropping.
.SH "EXIT VALUE"
Exits with a non-zero status if there were any processing errors.
Having
.I no
fonts present counts as a processing error.
.PP
If there is at least one font present, then missing fonts will be
replaced by the first
.I 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
.I "\-q"
option is not present,
but it will return with a zero (success) status.
.PP
Exception: If the
.I "\-n"
option is present, then the program returns success only if
.I all
fonts are present.
.SH FONT STRING TEMPLATES
The search-path and font-finder routes use font-string templates.
Here, the components of a font file name, or a font-finding command,
are specified using placeholders like
.I %f.
You may use
.TS
center ;
c	l .
Code	Substitution
\f(CR%M\fP	mode (eg. ibmvga)
\f(CR%f\fP	font name (eg. cmr10)
\f(CR%d\fP	dpi (eg. 330)
\f(CR%b\fP	base dpi (eg. 110)
\f(CR%m\fP	magnification (eg. 3)
\f(CR%%\fP	%
.TE
Thus, using these values as an example, if one of the entries in
.I DVI2BITMAP_PK_PATH
were 
.I /var/tmp/%M/%f.%dpk
, this would expand into
.I /var/tmp/ibmvga/cmr10.330pk
Alternatively, if we had given the font-finder script as 
.I /usr/local/teTeX/bin/kpsewhich pk %f.%dpk
, then
.I dvi2bitmap
would have executed the command
.I ".../kpsewhich pk cmr10.330pk"
, which would have returned with a suitable font path.
.SH EXAMPLES
    \f(CR% dvi2bitmap --resolution=110 --magnification=2 \e
        --scale=2 --output-type=gif hello.dvi\fP
.br
This converts the file 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.
.PP
    \f(CR% dvi2bitmap -n --query=missing-fonts --resolution=110 \e
        --magnification=1.5 --verbose=quiet hello.dvi
    Qmissing-fonts cmr10 165 110 1.5 localfont\fP
.br
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.
.PP
How you generate fonts depends on your TeX distribution.  As explained
above, you can determine which fonts you need using the 
.I "\--query=missing-fonts"
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 above
example would be:
    % MakeTeXPK cmr10 165 110 1.5 ibmvga
.br
assuming you want to use the 
.I ibmvga
metafont mode.  If you want to use the same mode as you use for other
documents, then the mode
.I 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 
.I ibmvga,
which has been tweaked to be readable at small resolutions.  See the file
.I "modes.mf"
somewhere in your metafont distribution for the list of possibilities.
.PP
If you're using the TeXLive distribution, the command would be:
    \f(CR% mktexpk --mfmode ibmvga --mag 1.5 --bdpi 110 --dpi 165 cmr10\fP
.PP
Then try giving the command
    \f(CR% kpsewhich pk cmr10.165pk\fP
.br
to confirm that TeX and friends can find the new fonts, and that your 
dvi2bitmap environment variable is set correctly.
.SH ENVIRONMENT
The 
.B DVI2BITMAP_PK_PATH
environment variable gives a colon-separated list of directories which
are to be searched for PK files.  If the required font is not found in
the directories specified in this list, then the kpathsea library is
used, if support for that was available at compile-time.
This variable is overridden by the 
.I "\--font-path"
option.  Each of the entries in this path is a `font string
template', as described above.
.PP
If the program was compiled with support for the kpathsea library,
then it will use that library to find fonts.  If you did
not install dvi2bitmap along with other TeXware, or if the the
program was not told where they live at configuration time, then you might
additionally have to specify the
.I "TEXMFCNF"
environment variable:
set it to the directory which contains the main TeX configuration
file, which you can find using the command
    \f(CRkpsewhich cnf texmf.cnf\fP
.SH "SEE ALSO"
DVItype and PKtoPX: Knuth programs 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
.I /tex-archive/systems/knuth/texware/dvitype.web
and 
.I /tex-archive/systems/knuth/pxl/pktopx.web.
.PP
.IR "The DVI Driver Standard, Level 0" ,
Available on CTAN, in directory 
.I /tex-archive/dviware/driv-standard.
This incorporates sections of the DVItype documentation.
.SH BUGS
.PP
If the program doesn't conform to the DVI Driver Standard, please let
me know.
.PP
There are probably too many options, but the program is designed to sit
inside layers of scripting as one element in a complicated toolbox, so
maybe it's defensible.
.PP
It would be nice to output a greater range of bitmap types.  Sometime....
.SH AUTHOR
Norman Gray (http://nxg.me.uk).
See the file
.I AUTHORS
for other contributors.