2.2 DVI specials

dvi2bitmap recognises several DVI special commands, and emits a warning if it finds any others.

The syntax of the special commands is

\special{dvi2bitmap <special-command>+ }

The <special-command> which the program recognises are:

default

Makes other special-commands in this same special affect defaults. See those commands for details.

outputfile <filename>

The output file used for the current page will be named 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 default command has been given, then this instead specifies the default filename pattern, and the `filename' should contain a single #-sign.

absolute

Affects the crop command.

crop <side> <dimen>

Crop the bitmap on the current page so that the specified edge of the bitmap is <dimen> points away from the bounding box of the blackened pixels. <side> may be one of `left', `right', `top', `bottom' or `all', referring to the corresponding edge, or all four edges at once. If the default command has been given in this special, then this pattern of cropping is additionally made the default for subsequent pages. If the absolute command has been given, then the crop position is set at <dimen> points from the appropriate edge of the `paper'.

The -c and -C command-line options (Section 2.1) have the effect of setting initial defaults. In the absence of either of these, the initial crop is exactly at the bounding box.

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 -t option (section Section 2.1).

The keyword is just imageformat, but you must specify the default keyword when you specify 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).

default foreground|background red green blue

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 imageformat you should at present always include the 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, 127=0177=0x7f).

strut left right top bottom

This places a `strut' in the generated file. Using the usual TeX \strut 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 dvi2bitmap fits its tight bounding box to the blackened pixels in the file, it knows nothing of the extra space you want.

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.

If you wanted to set a page containing only the maths `${}^\circ$' (why, is another matter), 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 \special{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.

A useful bit of TeX magic is:

{\catcode`p=12 \catcode`t=12 \gdef\DB@PT#1pt{#1}}
\def\DBstrut{\strut\special{dvi2bitmap strut 0 0 
\expandafter\DB@PT\the\ht\strutbox\space\expandafter\DB@PT\the\dp\strutbox}}

Once you've done that, the command \DBstrut will put an appropriate strut in the output.

For example, the pair of commands

\special{dvi2bitmap default outputfile trial-#.gif crop all 5}
\special{dvi2bitmap absolute crop left 0}