summaryrefslogtreecommitdiff
path: root/dviware/dvi2bitmap/dvi2bitmap.1.in
blob: 39e336d900df842d8fc0d115f81d22e9072370df (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
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 <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.