DVI2BITMAP(1) DVI2BITMAP(1) NNAAMMEE dvi2bitmap SSYYNNOOPPSSIISS ddvvii22bbiittmmaapp [-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 DDEESSCCRRIIPPTTIIOONN dvi2bitmap processes a DVI file produced by the TeX type- setting system, converting each page to a single bitmap. This man-page documents dvi2bitmap version _0_._9_-_6 This program is intended to conform to the DVI processing standard. The principal documentation for this package is in the HTML document distributed with it. This man-page may dif- fer from the documentation there. OOPPTTIIOONNSS _-_b_h _s_i_z_e_, _-_b_w _s_i_z_e 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 _W_a_r_n_i_n_g_: _p_._1_2_: _b_i_t_m_a_p _t_o_o _b_i_g_: _o_c_c_u_p_i_e_s _(_1_1_8_3_,_1_0_7_2_)_._._._(_4_1_3_4_,_6_2_5_5_)_. _R_e_q_u_e_s_t_e_d _4_1_0_0_x_6_2_0_0 then you'll need to specify a bitmap size. The numbers _(_1_1_8_3_,_1_0_7_2_)_._._._(_4_1_3_4_,_6_2_5_5_) are the coordinates of the top-left and bottom-right of the bitmap: in this case _-_b_h _6_3_0_0 _-_b_w _4_2_0_0 would suffice. Note that the `h' in _-_b_h stands for height, not horizon- tal! At some point, I'd like to make the bitmap `expandable', obviating the need for these options. _-_b_p _p_a_p_e_r_s_i_z_e Set the initial size of the bitmap to be one of the paper sizes returned by _-_Q_p_. This is useful either to make sure that there is enough room on the ini- tial bitmap, to avoid the warning above, or, along with the _-_P_C option, to force the output bitmap to be a certain size. April 2000 1 DVI2BITMAP(1) DVI2BITMAP(1) _-_c_[_e_d_g_e_] _d_i_m_e_n_, _-_C_[_e_d_g_e_] _d_i_m_e_n The _-_c and _-_C options allow you to control how the generated bitmaps are cropped before they are writ- ten. The _[_e_d_g_e_] 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 _d_i_m_e_n 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 _d_i_m_e_n points from the left or top of the `page'. The specification _-_C _d_i_m_e_n , 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 below for TeX _\_s_p_e_c_i_a_l commands which set this within the TeX file. _-_f_p _f_o_n_t_-_p_a_t_h Specifies the path to the PK fonts which dvi2bitmap will use. See also the discussion of font search- ing below. _-_f_m _m_o_d_e Set the MetaFont mode which is used for generating font files. The default is _i_b_m_v_g_a_. If you set this, you will probably have to set the resolution to a consistent number. _-_f_g_, _-_f_G Switch automatic generation of fonts off and on, respectively. The default is set at compile time. _-_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 gen- eration (`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 _p_a_g_e_n_u_m See option _-_p _-_m _m_a_g_n_i_f_i_c_a_t_i_o_n The TeX magnification parameter which is used when processing the DVI file. It is a float, with 1.0 April 2000 2 DVI2BITMAP(1) DVI2BITMAP(1) corresponding to no magnification (the default). This interacts with the resolution as follows: if you specify a resolution of 100, and a magnifica- tion 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 _-_Q_f option. If this option is present, then the program returns non-zero if any fonts were missing. _-_n_n 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 _o_u_t_p_u_t Choose the output filename pattern. The value is a `printf' formatting string, with a single _%_d for- matting descriptor, which will be replaced in out- put filenames with the page number. This can be overridden on a per-page basis by a TeX _\_s_p_e_c_i_a_l embedded in the DVI file (see below). If there is no file extension, or if it does not match the out- put type, a suitable file extension will be added. _-_p _p_n_u_m_, _-_l _l_n_u_m_, _-_p_p _p_a_g_e_l_i_s_t These select page ranges, using a slight extension of the notation used by _d_v_i_p_s (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 _p_n_u_m to page _l_n_u_m , with the defaults being the corresponding extremes. The _p_a_g_e_l_i_s_t 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 speci- fications may be prefixed by either _= or _:_n_, In the former case, DVI page numbers are used rather than TeX _\_c_o_u_n_t registers; in the latter case, the pro- gram examines the _\_c_o_u_n_t_n register rather than the default _\_c_o_u_n_t_0 You can specify both of these prefixes one or more times, but you cannot mix the _-_p and _-_l options with the _-_p_p option. The program will respect only the last _-_p and _-_l options, but the _-_p_p options are cumulative. There may be no spaces in the _p_a_g_e_- _l_i_s_t_. The page numbers may be negative. Examples: April 2000 3 DVI2BITMAP(1) DVI2BITMAP(1) _d_v_i_2_b_i_t_m_a_p _-_p_p _3_,_6_-_1_0 _._._. process only the specified pages _d_v_i_2_b_i_t_m_a_p _-_p_p _:_2_,_1 _._._. process only pages where _\_c_o_u_n_t_2 was 1. _-_P_[_B_b_T_t_C_c_] Specifies processing of the output bitmap. _-_P_b 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 _-_P_t option makes the output bitmap have a transparent background, if that's supported by the particular format you choose using option _-_t The _-_P_c option specifies that you want the output bitmap to be cropped. This is done by default, so you'll more often use the _-_P_C option to specify that you do not want the output cropped (for exam- ple, if you're using the _-_b_p option and want the output to stay the specified size). The options _-_P_B , _-_P_C and _-_P_T 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 _d_v_i_2_b_i_t_m_a_p 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 trans- parency 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 back- ground colour when making such transparent PNGs. I'd welcome advice on this point. _-_q Quiet mode -- suppress some chatter. _-_q_q Silent mode -- do not display warnings or errors. April 2000 4 DVI2BITMAP(1) DVI2BITMAP(1) _-_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 _-_Q_F option would start _Q_F _c_m_b_x_1_0 _1_1_0 _._._. Some of these options ( _-_Q_f and _-_Q_g ) are probably most useful with the _-_n option, to investigate a DVI file before processing. Others ( _-_Q_t and _-_Q_p ) are probably useful only with _-_n_n_. _-_Q_b 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 _-_n_n is implied in any of them, and you have to give it explicitly. _-_Q_b Prints on stdout a line for each bitmap it gener- ates, giving the filename, horizontal size, and vertical size, in pixels. _-_Q_f Show missing fonts. The program writes on standard output one line per missing font, starting with _Q_f , then five fields: the font name, the DPI value it was looking for, the base-DPI of the font, the mag- nification 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 _-_Q_g is more straightfor- ward. _-_Q_F As for _-_Q_f except that found fonts are also listed, prefixed by _Q_F _-_Q_g As for _-_Q_f , except that the output consists of the string _Q_g followed by a _m_k_t_e_x_p_k or _M_a_k_e_T_e_X_P_K com- mand which can be used to generate the font. _-_Q_G As for _-_Q_f , except that found fonts are also listed, prefixed by _Q_G Only one of _-_Q_f , _-_Q_F , _-_Q_g and _-_Q_G should be specified -- if more than one appears, only the last one is respected. _-_Q_p Show the list of paper sizes which are predefined for the _-_b_p option. _-_Q_t List the output image formats which the program can generate, on stdout, separated by whitespace. The first output format is the default. _-_r _r_e_s_o_l_u_t_i_o_n 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_b_m_v_g_a metafont mode. April 2000 5 DVI2BITMAP(1) DVI2BITMAP(1) _-_R_[_f_b_] _i_n_t_,_i_n_t_,_i_n_t Specifies the foreground ( _-_R_f ) or background ( _-_R_b ) 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, _1_2_7_=_0_1_7_7_=_0_x_7_f ). _-_s _s_c_a_l_e_f_a_c_t_o_r Reduces the linear size of the output bitmap by a factor _s_c_a_l_e_f_a_c_t_o_r (default 1). _-_t _t_y_p_e Choose the output format, which can be _p_n_g , _g_i_f or _x_b_m default. 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. DDVVII ssppeecciiaallss dvi2bitmap recognises several DVI special commands, and emits a warning if it finds any others. The syntax of the special commands is \special{dvi2bitmap + } There may be one or more _<_s_p_e_c_i_a_l_-_c_o_m_m_a_n_d_> sequences within a single special. The _<_s_p_e_c_i_a_l_-_c_o_m_m_a_n_d_> which the program recognises are: _d_e_f_a_u_l_t Makes other special-commands in this same special affect defaults. See those commands for details. _o_u_t_p_u_t_f_i_l_e _<_f_i_l_e_n_a_m_e_> The output file used for the current page will be named _f_i_l_e_n_a_m_e_._g_i_f (if the output type were `gif'). A filename extension will be added if none is pre- sent, or if it does not match the output type selected. If the _d_e_f_a_u_l_t command has been given, then this instead specifies the default filename pattern, and the `filename' should contain a single _# -sign. _a_b_s_o_l_u_t_e Affects the _c_r_o_p command. _c_r_o_p _<_s_i_d_e_> _<_d_i_m_e_n_> Crop the bitmap on the current page so that the specified edge of the bitmap is _<_d_i_m_e_n_> points away from the bounding box of the blackened pixels. April 2000 6 DVI2BITMAP(1) DVI2BITMAP(1) _<_s_i_d_e_> may be one of `left', `right', `top', `bot- tom' or `all', referring to the corresponding edge, or all four edges at once. If the _d_e_f_a_u_l_t command has been given in this special, then this pattern of cropping is additionally made the default for subsequent pages. If the _a_b_s_o_l_u_t_e command has been given, then the crop position is set at _<_d_i_m_e_n_> points from the appropriate edge of the `paper'. The _-_c and _-_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. _d_e_f_a_u_l_t _i_m_a_g_e_f_o_r_m_a_t _<_f_o_r_m_a_t_> 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. The keyword is just _i_m_a_g_e_f_o_r_m_a_t , but you must specify the _d_e_f_a_u_l_t keyword when you specify _i_m_a_g_e_- _f_o_r_m_a_t ; 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). _d_e_f_a_u_l_t _f_o_r_e_g_r_o_u_n_d_|_b_a_c_k_g_r_o_u_n_d _r_e_d _g_r_e_e_n _b_l_u_e Sets the (default) foreground and background colours for text. This works, as long as you spec- ify 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 you should at present always include the keyword when using this special. The integers must be in the range [0,255], and can be specified in decimal, octal or hex (ie, _1_2_7_=_0_1_7_7_=_0_x_7_f ). _s_t_r_u_t _l_e_f_t _r_i_g_h_t _t_o_p _b_o_t_t_o_m This places a `strut' in the generated file. Using the usual TeX _\_s_t_r_u_t 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 loca- tions), so when _d_v_i_2_b_i_t_m_a_p fits its tight bounding box to the blackened pixels in the file, it knows nothing of the extra space you want. April 2000 7 DVI2BITMAP(1) DVI2BITMAP(1) 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 spe- cial 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 _$_{_}_^_\_c_i_r_c_$ (why, is another matter), _d_v_i_2_b_i_t_m_a_p would normally make a tight bounding box for the bitmap, so that you'd get an image contain- ing only the circle (unless other crop options were in force). If, in this case, you put in a special such as _\_s_p_e_c_i_a_l_{_d_v_i_2_b_i_t_m_a_p _s_t_r_u_t _0 _2 _1_0 _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 _\_D_B_s_t_r_u_t 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} 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. EEXXIITT VVAALLUUEE Exits with a non-zero status if there were any processing errors. Having _n_o fonts present counts as a processing error. If there is at least one font present, then missing fonts will be replaced by the first _c_m_r_1_0 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 _-_q option is not present, but it will return with a zero (success) status. April 2000 8 DVI2BITMAP(1) DVI2BITMAP(1) Exception: If the _-_n option is present, then the program returns success only if _a_l_l fonts are present. EEXXAAMMPPLLEESS % dvi2bitmap -r 110 -m 2 -s 2 -t gif hello.dvi This converts the file hello.dvi to a GIF bitmap. It first sets the magnification factor to 2, so that the pro- gram 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. % dvi2bitmap -n -Qf -r 110 -m 1.5 -q hello.dvi cmr10 165 110 1.5 localfont 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 parame- ters which could be used to generate the font files. How you generate fonts depends on your TeX distribution. As explained above, you can determine which fonts you need using the _-_l option. The teTeX and TeXLive TeX distribu- tions 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: % MakeTeXPK cmr10 165 110 1.5 ibmvga assuming you want to use the _i_b_m_v_g_a metafont mode. If you want to use the same mode as you use for other documents, then the mode _l_o_c_a_l_f_o_n_t should do the right thing. Other- wise, and probably better if these images are intended for the screen rather than paper, you could use a more spe- cialised mode such as _i_b_m_v_g_a_, which has been tweaked to be readable at small resolutions. See the file _m_o_d_e_s_._m_f somewhere in your metafont distribution for the list of possibilities. If you're using the TeXLive distribution, the command would be: % mktexpk --mfmode ibmvga --mag 1.5 --bdpi 110 --dpi 165 cmr10 Then try giving the command % kpsewhich pk cmr10.165pk to confirm that TeX and friends can find the new fonts, and that your dvi2bitmap environment variable is set cor- rectly. April 2000 9 DVI2BITMAP(1) DVI2BITMAP(1) EENNVVIIRROONNMMEENNTT The DDVVII22BBIITTMMAAPP__PPKK__PPAATTHH 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 direc- tories specified in this list, then the kpathsea library is used, if support for that was available at compile- time. This variable is overridden by the _-_f option. 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 con- figuration time, then you might additionally have to spec- ify the _T_E_X_M_F_C_N_F environment variable: set it to the directory which contains the main TeX configuration file, which you can find using the command _k_p_s_e_w_h_i_c_h _c_n_f _t_e_x_m_f_._c_n_f SSEEEE AALLSSOO 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 _/_t_e_x_-_a_r_c_h_i_v_e_/_s_y_s_- _t_e_m_s_/_k_n_u_t_h_/_t_e_x_w_a_r_e_/_d_v_i_t_y_p_e_._w_e_b and _/_t_e_x_-_a_r_c_h_i_v_e_/_s_y_s_- _t_e_m_s_/_k_n_u_t_h_/_p_x_l_/_p_k_t_o_p_x_._w_e_b_. _T_h_e _D_V_I _D_r_i_v_e_r _S_t_a_n_d_a_r_d_, _L_e_v_e_l _0, Available on CTAN, in directory _/_t_e_x_-_a_r_c_h_i_v_e_/_d_v_i_w_a_r_e_/_d_r_i_v_-_s_t_a_n_d_a_r_d_. This incor- porates sections of the DVItype documentation. BBUUGGSS There are way too many options. I'd better switch to using _g_e_t_o_p_t_s as soon as I get the chance. If the program doesn't conform to the DVI Driver Standard, please let me know. 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. It would be nice to output a greater range of bitmap types. Sometime.... AAUUTTHHOORR Norman Gray (norman@astro.gla.ac.uk) April 2000 10