summaryrefslogtreecommitdiff
path: root/dviware/dvi2bitmap/dvi2bitmap.1
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /dviware/dvi2bitmap/dvi2bitmap.1
Initial commit
Diffstat (limited to 'dviware/dvi2bitmap/dvi2bitmap.1')
-rw-r--r--dviware/dvi2bitmap/dvi2bitmap.1923
1 files changed, 923 insertions, 0 deletions
diff --git a/dviware/dvi2bitmap/dvi2bitmap.1 b/dviware/dvi2bitmap/dvi2bitmap.1
new file mode 100644
index 0000000000..9f29dee476
--- /dev/null
+++ b/dviware/dvi2bitmap/dvi2bitmap.1
@@ -0,0 +1,923 @@
+.TH DVI2BITMAP 1 "2000 January 1"
+.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 "1.0"
+.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 <osfile>dvi-file
+(which is entirely equivalent) or
+.I <osfd>integer
+, where the given integer specifies an open file descriptor;
+specifying
+.I "-"
+as the input file is equivalent to
+.I <osfd>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 <special-command>+ }\fP
+.br
+There may be one or more
+.I "<special-command>"
+sequences within a single special.
+.PP
+The
+.I "<special-command>"
+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 <filename>"
+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 <side> <dimen>"
+Crop the bitmap on the current page so that the specified edge of
+the bitmap is
+.I "<dimen>"
+points away from the bounding box of the blackened pixels.
+.I "<side>"
+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 "<dimen>"
+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 <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
+.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 <left> <right> <top> <bottom>"
+.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 <u>"
+.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.