From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- dviware/dvi2bitmap/dvi2bitmap.1.in | 923 +++++++++++++++++++++++++++++++++++++ 1 file changed, 923 insertions(+) create mode 100644 dviware/dvi2bitmap/dvi2bitmap.1.in (limited to 'dviware/dvi2bitmap/dvi2bitmap.1.in') diff --git a/dviware/dvi2bitmap/dvi2bitmap.1.in b/dviware/dvi2bitmap/dvi2bitmap.1.in new file mode 100644 index 0000000000..39e336d900 --- /dev/null +++ b/dviware/dvi2bitmap/dvi2bitmap.1.in @@ -0,0 +1,923 @@ +.TH DVI2BITMAP 1 "@RELEASEDATE@" +.SH NAME +dvi2bitmap +.SH SYNOPSIS +.B dvi2bitmap +[flags] dvi-file +.SH DESCRIPTION +dvi2bitmap processes a DVI file produced by the TeX typesetting +system, converting each page to a single bitmap. +.PP +This man-page documents +.I dvi2bitmap +version +.I "@VERSION@" +.PP +This program is intended to conform to the DVI processing standard. +.PP +The principal documentation for this package is in the HTML document +distributed with it. This man-page may differ from the documentation +there. +.PP +The +.I dvi-file +argument is the name of a DVI file to be converted to a bitmap. +dvi2bitmap looks for the file both with and without the default +extension +.I .dvi +.PP +You may also read the DVI file from the standard input by giving the +DVI file as +.I "-" +, thus + \f(CRcat myfile.dvi | dvi2bitmap -\fP +.br +is an alternative way of reading the file (rather pointless in this +case, but it shows the principle). +For more arcane purposes, the DVI file may also be specified as +.I dvi-file +(which is entirely equivalent) or +.I integer +, where the given integer specifies an open file descriptor; +specifying +.I "-" +as the input file is equivalent to +.I 0 +.SS OPTIONS +.PP +Various of the options below have common syntax features. +.TP +.I [keyword-list] +This indicates a sequence of +.I keyword=value +pairs, separated by commas. Not all keywords necessarily have a +value. +.TP +.I [boolean] +This can be `yes', `true' or `on' indicating +.I true +, or `no', `false' or `off' indicating +.I false. +.PP +The options are as follows: +.TP +.I "-c, --crop=[keyword-list]" +.\" .I "\-c[edge] dimen, \-C[edge] dimen" +The +.I "--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 +.I "--crop=absolute,all=dimen" +, which would set all +the crops to the same position, is silly, and so is forbidden. +.IP +You should specify the crop option +.I after +the +.I --magnification +option, to ensure that the conversion from points to pixels takes +account of that. The conversion currently takes no account of any +magnification in the DVI file, nor of the +.I --scaledown +option. This is less of a burden than it might seem, since in the +presence of magnifications and resolutions, determining the crop +margin size is more of a matter of trial-and-error than you might expect. +.IP +See below for TeX +.I "\especial" +commands which set this within the TeX file. +.TP +.I "-F, --font-search=[keyword-list]" +Specifies how +.I dvi2bitmap +is to find the fonts it needs. Keywords are as follows: +.IP +.I path[=list] +: use the given colon-separated list of filesystem paths to search for PK +fonts, or enable using the default path, if the list is +missing. The default path is given by the environment variable +.I DVI2BITMAP_PK_PATH. +See also the discussion of font searching below. +.IP +.I kpathsea +: enable using the +.I kpathsea +library to find fonts. If the program was not built against the +.I kpathsea +library, this option has no effect. +.IP +.I 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 + \f(CR--font-search=command="kpsewhich pk %f.%dpk"\fP +.br +to run the +.I kpsewhich +program. The command name is a font-string +template, as described below. +.IP +If the program does not find a font using whichever methods have +been enabled then, following the pattern of +.I dvips +and other DVIware, it writes a file +.I missfont.log +in the current directory, containing commands which you can use to generate +the fonts immediately or later. +.IP +.I none +: disable all font-searching. The result is that +only the +.I missfont.log +file is written. +.IP +Each of the keywords can be prefixed by `no' to turn off the +corresponding option -- thus +.I --font-search=nopath,nokpathsea,nocommand +has the same effect as +.I --font-search=none +.TP +.I "-G, --font-gen=[[boolean]|command[=script]]" +Switch automatic generation of fonts off and on. +If +.I --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. +.TP +.I "-g, --debug=[spec]" +Switch on debugging. The +.I [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). +.TP +.I "-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 +.I "Warning: p.12: bitmap too big: occupies (1183,1072)...(4134,6255). Requested 4100x6200" +then +you'll need to specify a bitmap size. The numbers +.I "(1183,1072)...(4134,6255)" +are the coordinates of the top-left and +bottom-right of the bitmap: in this case +.I "--height=6300 --width=4200" +would suffice. At some point, I'd like to make the bitmap +`expandable', obviating the need for these options. +.TP +.I "--help" +Display simple help for the options on stderr, and exit. +.TP +.I "-l, --end-page" +See option +.I "--start-page" +.TP +.I "-M, --font-mode=[mode]" +Set the MetaFont mode which is used for generating font files. The +default is +.I "ibmvga." +If you set this, you will probably have to set the resolution to a consistent +number. +.TP +.I "-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 +.I dvi2bitmap +will search for PK files at 200 dpi. +.TP +.I "-n, --nodvi" +Do not actually process the DVI file, but read the DVI pre- and +postamble. Useful in conjunction with the +.I "--query" +options. If this option is present, then the program returns non-zero +if any fonts were missing. The +.I "-n" +is for brevity and consistency with other tools -- the behaviour can +be alternatively specified as +.I "--process=nodvi" +.TP +.I "-o, --output=[filename-pattern]" +Choose the output filename pattern. If there is a +.I "%d" +string within the pattern, then this pattern will be used for each +output file name, with the +.I "%d" +replaced by the page number. If there is no such string, then this +will be taken to be the name of the +.I first +page output, after which the filename pattern will revert to the default. +This can be overridden on a per-page basis by a TeX +.I "\especial" +embedded in the DVI file (see below). If there is no +file extension, or if it does not match the output type, a suitable file +extension will be added. +.TP +.I --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, "-". +.TP +.I "-p, --start-page=num" +.TP +.I "-l, --end-page=num" +.TP +.I "-P, --page-range=[spec]" +These select page ranges, using a slight extension of the notation +used by +.I "dvips" +(and the same option letters, except that +.I dvips +uses +.I -pp +instead of +.I -P +). +.IP +The +.I "--start-page=snum" +and +.I "--end-page=enum" +options take single page numbers; if +either of these is given, then the program will process pages from +page +.I "snum" +to page +.I "enum" +, with the defaults being the +corresponding extremes. The +.I "[spec]" +consists of a +comma-separated sequence of page numbers and ranges ( +.I "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 '\f(CR=\fP' or '\f(CR:n:\fP'. In the former case, DVI page +numbers are used rather than the TeX +.I "\ecount0" +register; in the latter case, the program examines the +.I "\ecountn" +register rather than the default +.I "\ecount0" +.IP +You can specify both of these prefixes one or more times, but you +cannot mix the +.I "--start-page" +and +.I "--end-page" +options with the +.I "--page-range" +option. The program will respect only the last +.I "--start-page" +and +.I "--end-page" +options, but the +.I "--page-range" +options are cumulative. There +may be no spaces in the +.I "pagelist." +The page numbers may be negative. +.IP +Examples: + \f(CRdvi2bitmap \--page-range=3,6\-10 ...\fP +.br +processes only the specified pages, and + \f(CRdvi2bitmap \--page-range=:2:1 ...\fP +.br +processes only pages where +.I "\ecount2" +was 1. +.TP +.I "-Q, --query=[keyword-list]" +Query various things. The available possibilities are as +follows. 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 +.I "--query=missing-fonts" +option would start + \f(CRQmissing-fonts cmbx10 110 ...\fP +.IP +Some of these options ( +.I --query=missing-fonts +and +.I --query=missing-fontgen +) are probably most +useful with the +.I "\-n" +or +.I --process=options +options, to investigate a DVI file before processing. Others ( +.I --query=types +and +.I --query=paper +) are probably useful only +with +.I --process=options. +The option +.I "--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 +.I --process +option is +.I not +implied in any of them, and you have to give it explicitly. +.TP +.I --query=bitmaps +Prints on stdout a line for each bitmap it generates, giving the +filename, horizontal size, and vertical size, in pixels. This will +also report the position of any `mark' in the bitmap; see special `mark' +below. +.TP +.I "-Qf, --query=missing-fonts" +Show missing fonts. +The program writes on standard output one line per missing font, +starting with +.I "Qf" +or +.I "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 +.I "--query=missing-fontgen" +is more straightforward. +.TP +.I "-QF, --query=all-fonts" +As for +.I "--query=missing-fonts" +except that found fonts are also listed, all prefixed by +.I "Qall-fonts" +.TP +.I "-Qg, --query=missing-fontgen" +As for +.I "--query=missing-fonts" +, except that the output consists of the string +.I "Qmissing-fontgen" +followed by a +.I "mktexpk" +or +.I "MakeTeXPK" +command which can be used to generate the font. +.TP +.I "-QG, --query=all-fontgen" +As for +.I --query=missing-fonts +, except that font-generation commands for found fonts are also +listed, prefixed by +.I "Qall-fontgen." +.IP +Only one of +.I --query=missing-fonts +, +.I --query=all-fonts +, +.I --query=missing-fontgen +and +.I --query=all-fontgen +should be specified -- 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 +.I --font-gen=true +.TP +.I --query=paper +Show the list of paper sizes which are predefined for the +.I --paper-size +option. +.TP +.I --query=types +List the output image formats which the program can generate, on +stdout, separated by whitespace. The first output format is the default. +.TP +.I "-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 +.I "ibmvga" +metafont mode. +.TP +.I "-R, --colours=[keyword-list], --colors=[keyword-list]" +Specifies the foreground or background colours, as RGB triples. The +keywords are either +.I foreground +or +.I background +, and the values are a triple of integers separated by slashes, for example +.I "--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 +.I "127=0177=0x7f" +), or else the whole spec may be of the form +.I "#rrggbb" +, where `rr', `gg' and `bb' are each a pair of hex digits. +.TP +.I "-s, --scaledown=[number]" +Reduces the linear size of the output bitmap by a factor +.I "scaledown" +(default 1). +.TP +.I "-T, --output=type=[type]" +Choose the output format, which can be +.I "png" +, +.I "gif" +, +.I "xpm" +or +.I "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. +.TP +.I "\-t, \-\-paper-size=papersize" +Set the initial size of the bitmap to be one of the paper sizes +returned by +.I "\-\-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 +.I "\-\-process=nocrop" +option, to force the output bitmap to be a certain size. +.TP +.I "-v, --verbose=[normal|quiet|silent]" +Quiet mode suppresses some chatter, and silent mode suppresses +chatter, and does not display warnings or errors either. Mode +`normal' is the default. +.TP +.I "-V, --version" +Display the version number and compilation options, and exit. +.TP +.I "-X, --process=[keyword-list]" +Specifies the processing to be done. +Keywords are as follows +.IP +.I dvi +and +.I 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 +.I nodvi +option is useful with some of the +.I --query +options. +.IP +.I postamble +and +.I 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 +.I --query +options which examine the fonts in the file. By default, both the +DVI body and the postamble are processed. +.IP +.I --process=options +: shorthand for +.I --process=nopreamble,nodvi,nopostamble. Only the options are examined +.IP +.I blur +and +.I 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 +.I "--magnification" +option to magnify the DVI file, and then the +.I "--scale" +option to scale it back down to the correct size. +.IP +.I transparent +and +.I notransparent +: option +.I transparent +makes the output bitmap have a transparent background, if +that's supported by the particular format you choose using option +.I "--output-type" +.IP +.I crop +and +.I nocrop +: if set, this specifies that you want the output bitmap to +be cropped. This is true by default, so you'll most often use the +.I nocrop +to specify that you do not want the output cropped +(for example, if you're using the +.I "--paper-size" +option and want the output to stay the specified size). +.IP +By default, bitmaps are not blurred, are cropped, and are transparent +if possible. +.IP +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 +.I 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. +.SH "DVI specials" +.I dvi2bitmap +recognises several DVI special commands, and emits a +warning if it finds any others. +.PP +The syntax of the special commands is + \f(CR\especial{dvi2bitmap + }\fP +.br +There may be one or more +.I "" +sequences within a single special. +.PP +The +.I "" +which the program recognises are: +.TP +.I "default" +Makes other special-commands in this same special affect +defaults. See those commands for details. +.TP +.I "outputfile " +The output file used for the current page will be named +.I "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. +.IP +If the +.I default +command has been given, then this instead specifies the default +filename pattern, and the `filename' should contain a single instance +of either +.I %d +or +.I # +; if there is no such instance, one will be implicitly added at the end. +.IP +The +.I %d +is precisely analogous to the behaviour of the +.I --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 +.I # +character to indicate where the +page number should go. In fact, since it is also rather +tricky to get a single +.I # +character in a special, any immediately following +.I # +characters are ignored. Thus the recommended way of specifying this +special is through something of the form + \f(CR\especial{dvi2bitmap default outputfile myfile-#}\fP +using the +.I # +form, and letting the file extension be controlled by the output type +which is actually used. +.TP +.I "absolute" +Affects the +.I "crop" +command. +.TP +.I "crop " +Crop the bitmap on the current page so that the specified edge of +the bitmap is +.I "" +points away from the bounding box of the blackened pixels. +.I "" +may be one of `left', +`right', `top', `bottom' or `all', referring to the corresponding +edge, or all four edges at once. If the +.I "default" +command has been given in this special, then this pattern of cropping is +additionally made the default for subsequent pages. If the +.I "absolute" +command has been given, then the crop position is set at +.I "" +points from the appropriate edge of the `paper'. +.IP +The +.I "-c" +and +.I "-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. +.TP +.I "default imageformat " +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 +.I --output-type +option. +.IP +The keyword is just +.I "imageformat" +, but you must specify the +.I "default" +keyword when you +specify +.I "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). +.TP +.I "default foreground|background red green blue" +.IP +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 +.I imageformat +you should at present always include the +.I 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, +.I "127=0177=0x7f" +). +.TP +.I "strut " +.IP +This places a `strut' in the generated file. Using the usual TeX +.I "\estrut" +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 +.I "dvi2bitmap" +fits its tight bounding box to the blackened pixels +in the file, it knows nothing of the extra space you want. +.IP +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; +they are floats rather than integers, but they are rounded to pixels +before being applied to the growing bitmap. +.IP +If you wanted to set a page containing only the maths +.I "${}^\ecirc$" +(why, is another matter), +.I "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 +.I "\especial{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. +.IP +A useful bit of TeX magic is: + \f(CR{\ecatcode`p=12 \ecatcode`t=12 \egdef\eDB@PT#1pt{#1}} + \egdef\eDBstrut{% + \estrut\especial{dvi2bitmap strut 0 0 + \eexpandafter\eDB@PT\ethe\eht\estrutbox + \espace\eexpandafter\eDB@PT\ethe\edp\estrutbox}}\fP +.br +Once you've done that, the command +.I "\eDBstrut" +will put an appropriate strut in the output. +.TP +.I mark +.IP +This sets a `mark' in the generated file, which is reported when +you specify +.I "--query=bitmaps." +Normally, +.I "--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 +.I "--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 + \f(CR\enoindent\especial{dvi2bitmap mark}Hello\fP +.br +the command line + \f(CRdvi2bitmap --query=bitmaps foo\fP +.br +might report + \f(CRQbitmaps foo-page1.png 80 14 -1 10\fP +.br +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. +.IP +There's a certain amount of ambiguity in the specification of where +the `mark' position should be reported (it's the standard question of +whether the centre of a pixel has integer or half-integer +coordinates). 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. +.TP +.I "unit " +.IP +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. +.PP +As an example, the pair of commands + \f(CR\especial{dvi2bitmap default outputfile trial-#.gif unit pc crop all 5} + \especial{dvi2bitmap absolute crop left 5}\fP +.br +will change the output filename pattern for the rest of the DVI file, +and set a 5pc margin round the bounding box. The current page, +however, will have a left-hand crop five 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. +.SH "EXIT VALUE" +Exits with a non-zero status if there were any processing errors. +Having +.I no +fonts present counts as a processing error. +.PP +If there is at least one font present, then missing fonts will be +replaced by the first +.I cmr10 +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 +.I "\-q" +option is not present, +but it will return with a zero (success) status. +.PP +Exception: If the +.I "\-n" +option is present, then the program returns success only if +.I all +fonts are present. +.SH FONT STRING TEMPLATES +The search-path and font-finder routes use font-string templates. +Here, the components of a font file name, or a font-finding command, +are specified using placeholders like +.I %f. +You may use +.TS +center ; +c l . +Code Substitution +\f(CR%M\fP mode (eg. ibmvga) +\f(CR%f\fP font name (eg. cmr10) +\f(CR%d\fP dpi (eg. 330) +\f(CR%b\fP base dpi (eg. 110) +\f(CR%m\fP magnification (eg. 3) +\f(CR%%\fP % +.TE +Thus, using these values as an example, if one of the entries in +.I DVI2BITMAP_PK_PATH +were +.I /var/tmp/%M/%f.%dpk +, this would expand into +.I /var/tmp/ibmvga/cmr10.330pk +Alternatively, if we had given the font-finder script as +.I /usr/local/teTeX/bin/kpsewhich pk %f.%dpk +, then +.I dvi2bitmap +would have executed the command +.I ".../kpsewhich pk cmr10.330pk" +, which would have returned with a suitable font path. +.SH EXAMPLES + \f(CR% dvi2bitmap --resolution=110 --magnification=2 \e + --scale=2 --output-type=gif hello.dvi\fP +.br +This converts the file hello.dvi to a GIF bitmap. It first sets the +magnification factor to 2, so that the program 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. +.PP + \f(CR% dvi2bitmap -n --query=missing-fonts --resolution=110 \e + --magnification=1.5 --verbose=quiet hello.dvi + Qmissing-fonts cmr10 165 110 1.5 localfont\fP +.br +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 parameters which could be used to generate the +font files. +.PP +How you generate fonts depends on your TeX distribution. As explained +above, you can determine which fonts you need using the +.I "\--query=missing-fonts" +option. The teTeX and TeXLive TeX distributions 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 +.br +assuming you want to use the +.I ibmvga +metafont mode. If you want to use the same mode as you use for other +documents, then the mode +.I localfont +should do the right thing. Otherwise, and probably better if these +images are intended for the screen rather than paper, you could use a +more specialised mode such as +.I ibmvga, +which has been tweaked to be readable at small resolutions. See the file +.I "modes.mf" +somewhere in your metafont distribution for the list of possibilities. +.PP +If you're using the TeXLive distribution, the command would be: + \f(CR% mktexpk --mfmode ibmvga --mag 1.5 --bdpi 110 --dpi 165 cmr10\fP +.PP +Then try giving the command + \f(CR% kpsewhich pk cmr10.165pk\fP +.br +to confirm that TeX and friends can find the new fonts, and that your +dvi2bitmap environment variable is set correctly. +.SH ENVIRONMENT +The +.B DVI2BITMAP_PK_PATH +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 directories 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 +.I "\--font-path" +option. Each of the entries in this path is a `font string +template', as described above. +.PP +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 configuration time, then you might +additionally have to specify the +.I "TEXMFCNF" +environment variable: +set it to the directory which contains the main TeX configuration +file, which you can find using the command + \f(CRkpsewhich cnf texmf.cnf\fP +.SH "SEE ALSO" +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 +.I /tex-archive/systems/knuth/texware/dvitype.web +and +.I /tex-archive/systems/knuth/pxl/pktopx.web. +.PP +.IR "The DVI Driver Standard, Level 0" , +Available on CTAN, in directory +.I /tex-archive/dviware/driv-standard. +This incorporates sections of the DVItype documentation. +.SH BUGS +.PP +If the program doesn't conform to the DVI Driver Standard, please let +me know. +.PP +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. +.PP +It would be nice to output a greater range of bitmap types. Sometime.... +.SH AUTHOR +Norman Gray (http://nxg.me.uk). +See the file +.I AUTHORS +for other contributors. -- cgit v1.2.3