2.1 Options

-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 Warning: 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

Set the initial size of the bitmap to be one of the paper sizes returned by -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

The -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

Specifies the path to the PK fonts which dvi2bitmap will use. See also Section 2.5.

-fm mode

Specify the MetaFont mode which is to be used when generating fonts. The default is ibmvga, but see --enable-fontgen in Section 3.1.

-fg

Switch off automatic font-generation.

-fG

Switch on automatic font-generation.

-g(d|p|r|i|b|m|g)

Switch on debugging. The options are to trace DVI file parsing (`d'), PK file parsing and kpathsea if installed (`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).

-l pagenum

See option -p

-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.

-n

Do not actually process the DVI file, but read the DVI pre- and postamble. Useful in conjunction with the -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

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 -Q.

-o output

Choose the output filename pattern. The value is a `printf' formatting string, with a single %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 pagelist

These select page ranges, using a slight extension of the notation used by dvips (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]

Specifies processing of the output bitmap.

-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

Quiet mode - suppress chatter. This also suppresses warnings.

-qq

Silent mode - suppress errors as well.

-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 -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

Prints on stdout a line for each bitmap it generates, giving the filename, horizontal size, and vertical size, in pixels.

-Qf

Show missing fonts. The program writes on standard output one line per missing font, starting with `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 -Qg is more straightforward.

-QF

As for -Qf, except that found fonts are also listed, prefixed by `QF'.

-Qg

As for -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

As for -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

Show the list of paper sizes which are predefined for the -bp option.

-Qt

List the output image formats which the program can generate, on stdout, separated by whitespace. The first output format is the default.

-r resolution

Specifies the output resolution, in pixels-per-inch. This is used when deciding which PK files to use. The default is 110, but see --enable-fontgen in Section 3.1.

-R[fb] int,int,int

Specifies the foreground (-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 scalefactor

Reduces the linear size of the output bitmap by a factor scalefactor (default 1).

-t type

Choose the output format, which can be png, xbm or gif. The GIF and PNG options may not be available if they weren't selected when the program was configured.

-V

Display the version number and compilation options, and exit.