.\" $Id: dvi2bitmap.1,v 1.25 2001/01/12 11:59:55 norman Exp $
.TH DVI2BITMAP 1 "April 2000"
.SH NAME
dvi2bitmap
.SH SYNOPSIS
.B dvi2bitmap 
    [\-b(h|w) size] [\-bp a4|a4l|usletter...]
    [\-[Cc][lrtb] size]
    [\-fp PKpath ] [\-fm mfmode] [\-fg] [\-fG]
    [\-g[dpribmg]] [\-m magmag ] [\-n[n]]
    [\-l num] [\-p num] [\-pp ranges] [\-o outfile-pattern]
    [\-P[bBtTcC]] [\-q[q]] [\-Q[FfGgtbp]]
    [\-r resolution] [\-R[fb] int,int,int] [\-s scale-factor]
    [\-t xbm|gif|png] [\-V]
    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 dvi2bitmap version
.\" %%VERSION%%
.I "0.9-6"
.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.
.SS OPTIONS
.TP
.I "\-bh size, \-bw 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 "\-bh 6300 \-bw 4200"
would suffice.  Note that the `h' in 
.I "\-bh"
stands for height, not horizontal!  At some point, I'd like to make the bitmap
`expandable', obviating the need for these options.
.TP
.I "\-bp papersize"
Set the initial size of the bitmap to be one of the paper sizes
returned by
.I "\-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
.I "\-PC"
option, to force the output bitmap to be a certain size.
.TP
.I "\-c[edge] dimen, \-C[edge] dimen"
The 
.I "\-c"
and
.I "\-C"
options allow you to control how the
generated bitmaps are cropped before they are written.  The
.I "[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 
.I "\-c"
option, this sets the crop to be
.I "dimen"
points from the specified edge of the
bounding box of the blackened pixels; in the case of the 
.I "\-C"
option, it sets it to be 
.I "dimen"
points from the left or top of
the `page'.  The specification 
.I "\-C dimen"
, which would set all
the crops to the same position, is silly, and so is forbidden.
.IP
The conversion from points to pixels takes account of the
magnification set in the 
.I "\-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. 
.P{
See below for TeX 
.I "\especial"
commands which set this within the TeX file.
.TP
.I "\-fp font-path"
Specifies the path to the PK fonts which dvi2bitmap will use.  See
also the discussion of font searching below.
.TP
.I "\-fm 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 "\-fg, \-fG"
Switch automatic generation of fonts off and on, respectively.  The
default is set at compile time.
.TP
.I "\-g(d|p|r|i|b|m|g)"
Switch on debugging.  The options are to 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 "-l pagenum"
See option 
.I "\-p"
.TP
.I "\-m magnification"
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 dvi2bitmap
will search for PK files at 200 dpi.
.TP
.I "\-n"
Do not actually process the DVI file, but read the DVI pre- and
postamble.  Useful in conjunction with the 
.I "\-Qf"
option.  If this option is present, then the program returns non-zero
if any fonts were missing.
.TP
.I "\-nn"
Do not process a DVI file at all, and do not require one to be
present on the command line.  Useful with some of options
.I "\-Q."
.TP
.I "\-o output"
Choose the output filename pattern.  The value is a 
`printf' formatting string, with a single
.I "%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
.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 "\-p pnum, \-l lnum, \-pp pagelist"
These select page ranges, using a slight extension of the notation
used by 
.I "dvips"
(and the same option letters).
.IP
The
.I "\-p"
and
.I "\-l"
options take single page numbers; if
either of these is given, then the program will process pages from
page 
.I "pnum"
to page 
.I "lnum"
, with the defaults being the
corresponding extremes.  The 
.I "pagelist"
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
.I "="
or
.I ":n,"
In the former case, DVI page
numbers are used rather than TeX
.I "\ecount"
registers; 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 "\-p"
and 
.I "\-l"
options with the 
.I "\-pp"
option.  The program will respect only the last 
.I "-p"
and
.I "\-l"
options, but the 
.I "\-pp"
options are cumulative.  There
may be no spaces in the 
.I "pagelist."
The page numbers may be negative.
.IP
Examples:
.IP
.I "dvi2bitmap \-pp 3,6\-10 ..."
.IP
process only the specified pages
.IP
.I "dvi2bitmap \-pp :2,1 ..."
.IP
process only pages where
.I "\ecount2"
was 1.
.TP
.I "\-P[BbTtCc]"
Specifies processing of the output bitmap.
.IP
.I "\-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
.I "\-m"
option to magnify the DVI file, and then the
.I "\-s"
option to scale it back down to the correct size.
.IP
The 
.I "\-Pt"
option makes the output bitmap have a transparent background, if
that's supported by the particular format you choose using option
.I "\-t"
.IP
The
.I "\-Pc"
option specifies that you want the output bitmap to
be cropped.  This is done by default, so you'll more often use the
.I "\-PC"
option to specify that you do not want the output
cropped (for example, if you're using the
.I "\-bp"
option and want the output to stay the specified size).
.IP
The options
.I "\-PB"
,
.I "\-PC"
and
.I "\-PT"
disable blurring, cropping and transparency, respectively.
.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.
.TP
.I "\-q"
Quiet mode -- suppress some chatter.
.TP
.I "\-qq"
Silent mode -- do not display warnings or errors.
.TP
.I "\-Q..."
Query various things.  The available possibilities are as
follows.  Each of these lines is printed on a line by itself, prefixed
by the option letters and a space, so that, for example, each of the
lines produced by the
.I "\-QF"
option would start
.I "QF cmbx10 110 ..."
.IP
Some of these options (
.I "\-Qf"
and
.I "\-Qg"
) are probably most
useful with the
.I "\-n"
option, to investigate a DVI file before processing.  Others (
.I "\-Qt"
and 
.I "\-Qp"
) are probably useful only
with
.I "\-nn."
.I "\-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
.I "\-n"
nor
.I "\-nn"
is implied in any of them, and you have to give it explicitly.
.TP
.I "\-Qb"
Prints on stdout a line for each bitmap it generates, giving the
filename, horizontal size, and vertical size, in pixels.
.TP
.I "\-Qf"
Show missing fonts.
The program writes on standard output one line per missing font,
starting with
.I "Qf"
, 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 "\-Qg"
is more straightforward.
.TP
.I "\-QF"
As for
.I "\-Qf"
except that found fonts are also listed, prefixed by
.I "QF"
.TP
.I "\-Qg"
As for
.I "\-Qf"
, except that the output consists of the string
.I "Qg"
followed by a 
.I "mktexpk"
or
.I "MakeTeXPK"
command which can be used to generate the font.
.TP
.I "\-QG"
As for
.I "\-Qf"
, except that found fonts are also listed, prefixed by
.I "QG"
Only one of 
.I "\-Qf"
,
.I "\-QF"
,
.I "\-Qg"
and
.I "\-QG"
should be specified -- if more than one appears, only the last
one is respected.
.TP
.I "\-Qp"
Show the list of paper sizes which are predefined for the
.I "\-bp"
option.
.TP
.I "\-Qt"
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"
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[fb] int,int,int"
Specifies the foreground (
.I "\-Rf"
) or background (
.I "\-Rb"
)
colour, as an RGB triple (
.I "\-R"
stands for RGB:
.I "\-c"
was already in use).  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 "\-s scalefactor"
Reduces the linear size of the output bitmap by a factor
.I "scalefactor"
(default 1).
.TP
.I "\-t type"
Choose the output format, which can be
.I "png"
,
.I "gif"
or
.I "xbm"
. The program generates XBM bitmaps by 
default.  The GIF and PNG options may not be available if they weren't
selected when the program was configured.
.TP
.I "\-V"
Display the version number and compilation options, and exit.
.SH "DVI specials"
dvi2bitmap recognises several DVI special commands, and emits a
warning if it finds any others.
.PP
The syntax of the special commands is 
.PP
\especial{dvi2bitmap <special-command>+ }
.PP
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.  If the
.I "default"
command has been given, then this instead specifies the
default filename pattern, and the `filename' should contain a single
.I "#"
-sign.
.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', `gif', `png'.  This is equivalent to specifying the image
format through the 
.I -t
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 <code/imageformat>
you should at present always include the <code/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, and
they are floats rather than integers.
.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:
.IP
{\ecatcode`p=12 \ecatcode`t=12 \egdef\eDB@PT#1pt{#1}}
\edef\eDBstrut{\estrut\especial{dvi2bitmap strut 0 0 
\eexpandafter\eDB@PT\ethe\eht\estrutbox
\espace\eexpandafter\eDB@PT\ethe\edp\estrutbox}}
.IP
Once you've done that, the command 
.I "\eDBstrut"
will put an appropriate strut in the output.

.PP
For example, the pair of commands
.IP
\especial{dvi2bitmap default outputfile trial-#.gif crop all 5}
\especial{dvi2bitmap absolute crop left 0}
.PP
will change the output filename pattern for the rest of the DVI file,
and set a 5pt margin round the bounding box.  The current page,
however, will have a left-hand crop zero 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 EXAMPLES
% dvi2bitmap -r 110 -m 2 -s 2 -t gif hello.dvi
.PP
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
% dvi2bitmap -n -Qf -r 110 -m 1.5 -q hello.dvi
.br
cmr10 165 110 1.5 localfont
.PP
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 "\-l"
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:
.PP
% MakeTeXPK cmr10 165 110 1.5 ibmvga
.PP
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:
.PP
% mktexpk --mfmode ibmvga --mag 1.5 --bdpi 110 --dpi 165 cmr10
.PP
Then try giving the command
.PP
% kpsewhich pk cmr10.165pk
.PP
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.
.PP
This variable is overridden by the 
.I "\-f"
option.
.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
.I "kpsewhich cnf texmf.cnf"
.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
There are way too many options.  I'd better switch to using 
.I "getopts"
as soon as I get the chance.
.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 (norman@astro.gla.ac.uk)