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 instance of either %d or #; if there is no such instance, one will be implicitly added at the end.

The %d is precisely analogous to the behaviour of the --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 # character to indicate where the page number should go. In fact, since it is also rather tricky to get a single # character in a special, any immediately following # characters are ignored. Thus the recommended way of specifying this special is through something of the form

\special{dvi2bitmap default outputfile myfile-#}

using the # form, and letting the file extension be controlled by the output type which is actually used.

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', `xpm' `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.

mark

This sets a `mark' in the generated file, which is reported when you specify --query=bitmaps (see item `-Q, --query=[keyword-list]'). Normally, --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 --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

\noindent\special{dvi2bitmap mark}Hello

the command line

dvi2bitmap --query=bitmaps foo

might report

Qbitmaps foo-page1.png 80 14 -1 10

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. See Section 3.4 for a discussion of how to do that.

Both here and in the support for the `strut' special, there is a great deal of scope for off-by-one errors; 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.

unit <u>

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.

For example, the pair of commands

\special{dvi2bitmap default outputfile trial-# unit pc crop all 5}
\special{dvi2bitmap absolute crop left 5}