2.1 Options

Various of the options below have common syntax features.

[keyword-value-list]

This indicates a sequence of keyword=value pairs, separated by commas. Not all keywords necessarily have a value.

[boolean]

This can be `yes', `true' or `on' indicating true; or `no', `false' or `off' indicating false.

The options are as follows:

-c, --crop=[keyword-value-pairs]

The --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 ----crop=absolute,all=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 --magnification 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.

See below for TeX \special commands which set this within the TeX file.

-F, --font-search=[keyword-value-list]

Specifies how dvi2bitmap is to find the fonts it needs. Keywords are as follows:

path[=list]: use the given list of filesystem paths to search for PK fonts, or enable using the default path, if =path is missing. The default path is given by the environment variable DVI2BITMAP_PK_PATH. See also the discussion of font searching below.

kpathsea: enable using the kpathsea library to find fonts. If the program was not built against the kpathsea library, this option has no effect.

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 kpsewhich pk %f.%dpk to run the kpsewhich program. The command name is a font-string template, as described elsewhere.

If the program does not find a font using whichever methods have been enabled then, following the pattern of dvips and other DVIware, it writes a file missfont.log in the current directory, containing commands which you can use to generate the fonts immediately or later.

none: disable all font-searching. The result is that only the missfont.log file is written.

Each of the keywords can be prefixed by `no' to turn off the corresponding option -- thus --font-search=nopath,nokpathsea,nocommand has the same effect as --font-search=none.

-G, --font-gen=[boolean], --font-gen=command[=script]

Switch automatic generation of fonts off and on. If --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.

-g, --debug=[spec]

Switch on debugging. The [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).

-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 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 --height=6300 --width=4200 would suffice. At some point, I'd like to make the bitmap `expandable', obviating the need for these options.

--help

Display outline help for the options on stderr, and exit

-l, --end-page

See option --start-page

-M, --font-mode=[mode]

Set the MetaFont mode which is used for generating font files. The default is ibmvga. If you set this, you will probably have to set the resolution to a consistent number.

-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 dvi2bitmap will search for PK files at 200 dpi.

-n, --nodvi

Do not actually process the DVI file, but read the DVI pre- and postamble. Useful in conjunction with the --query options. If this option is present, then the program returns non-zero if any fonts were missing (see also Section 2.3). The -n is for brevity and consistency with other tools -- the behaviour can be alternatively specified as --process=nodvi

-o, --output=[filename-pattern]

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. If there is no such descriptor, the filename `pattern' is used as-is for the first filename output, after which the program reverts to the default filename pattern. The filename pattern can be overridden on a per-page basis by a TeX \special embedded in the DVI file (see the outputfile special 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.

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

-p, --start-page=num, -l, --end-page=num, -P, --page-range=[spec]

These select page ranges, using a slight extension of the notation used by dvips (and the same option letters, except that dvips uses -pp instead of -P).

The --start-page=snum and --end-page=enum options take single page numbers; if either of these is given, then the program will process pages from page snum to page enum, with the defaults being the corresponding extremes. The [spec] 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 the TeX \count0 register; in the latter case, the program examines the \countn register rather than the default \count0

You can specify both of these prefixes one or more times, but you cannot mix the --start-page and --end-page options with the --page-range option. The program will respect only the last --start-page and --end-page options, but the --page-range options are cumulative. There may be no spaces in the pagelist. The page numbers may be negative.

Examples:

dvi2bitmap --page-range=3,6-10 ...

process only the specified pages

dvi2bitmap --page-range=:2:1 ...

process only pages where \count2 was 1.

-Q, --query=[keyword-list]

Query various things. The available possibilities are as given below. 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 --query=missing-fonts option would start Qmissing-fonts cmbx10 110 ...

Some of these options (--query=missing-fonts and --query=missing-fontgen) are probably most useful with the -n or --process=options options, to investigate a DVI file before processing. Others (--query=types and --query=paper) are probably useful only with --process=options. The option --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 --process option is not implied in any of them, and you have to give it explicitly.

--query=bitmaps

Prints on stdout a line for each bitmap it generates, giving the filename, horizontal size, and vertical size, in pixels. This also reports the position of any `mark' in the bitmap -- see item `mark'.

-Qf, --query=missing-fonts

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

-QF, --query=all-fonts

As for --query=missing-fonts except that found fonts are also listed, all prefixed by Qall-fonts

-Qg, --query=missing-fontgen

As for --query=missing-fonts, except that the output consists of the string Qmissing-fontgen followed by a mktexpk or MakeTeXPK command which can be used to generate the font.

-QG, --query=all-fontgen

As for --query=missing-fonts, except that font-generation commands for found fonts are also listed, prefixed by Qall-fontgen.

Note: Only one of --query=missing-fonts, --query=all-fonts, --query=missing-fontgen and --query=all-fontgen should be specified -- if more than one appears, only the last one is respected -- 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 --font-gen=true

--query=paper

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

--query=types

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

-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 ibmvga metafont mode.

-R, --colours=[keyword-value-list], --colors=[keyword-value-pairs]

Specifies the foreground or background colours, as RGB triples. The keywords are either foreground or background, and the values are a triple of integers separated by slashes, for example --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 127=0177=0x7f), or else the whole spec may be of the form #rrggbb, where `rr', `gg' and `bb' are each a pair of hex digits.

-s, --scaledown=[number]

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

-T, --output=type=[type]

Choose the output format, which can be png, gif, xpm or 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.

-t, --paper-size=papersize

Set the initial size of the bitmap to be one of the paper sizes returned by --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 --process=nocrop option, to force the output bitmap to be a certain size.

-v, --verbose=[quiet|silent]

Quiet mode suppresses some chatter, and silent mode suppresses chatter, and does not display warnings or errors either.

-V, --version

Display the version number and compilation options, and exit.

-X, --process=[keyword-value-list]

Specifies the processing to be done. Keywords are as follows:

dvi and 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 nodvi option is useful with some of the --query options.

postamble and 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 --query options which examine the fonts in the file. By default, both the DVI body and the postamble are processed.

--process=options: shorthand for --process=nopreamble,nodvi,nopostamble. Only the options are examined.

blur and 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 --magnification option to magnify the DVI file, and then the --scale option to scale it back down to the correct size.

transparent and notransparent: if true, this makes the output bitmap have a transparent background, if that's supported by the particular format you choose using option --output-type

crop and nocrop: if true, specifies that you want the output bitmap to be cropped. This is true by default, so you'll most often use the crop=false to specify that you do not want the output cropped (for example, if you're using the --paper-size option and want the output to stay the specified size).

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.