summaryrefslogtreecommitdiff
path: root/Build/source/texk/dvipng/dvipng.texi
blob: 352938caf8c8ca6bfbf2722a35f55bda0066241a (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
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
\input texinfo
@setfilename dvipng.info
@settitle A DVI-to-PNG translator
@ifset man
@c man begin SYNOPSIS
dvipng [options] filename

dvipng [options] [filename] -
@c man end
@end ifset

@set version 1.9
@set month-year November 2006

@c Put everything in one index (arbitrarily chosen to be the concept index).
@syncodeindex fn cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex vr cp

@include macros.texi
@iftex
@tolerance 10000 @emergencystretch 3em
@end iftex

@dircategory TeX
@direntry
* DVI-to-PNG: (dvipng).              Translating TeX DVI files to Portable Network Graphics (PNG).
* dvipng: (dvipng).                  A DVI-to-PNG translator.
@end direntry

@finalout
@titlepage
@title dvipng
@subtitle A DVI-to-PNG Translator
@subtitle Version @value{version}


@author by Jan-@AA{}ke Larsson.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2002-2006 Jan-@AA{}ke Larsson
 
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``Copying'' is included exactly as in the original, and
provided that the entire resulting derived work is distributed under the
terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@end titlepage
@page

@c @summarycontents
@contents

@ifnottex
@node Top
@top dvipng

This manual documents dvipng, a program to translate a DVI (DeVice
Independent) file into PNG (Portable Network Graphics).

This file documents dvipng version @value{version}

Corrections or perhaps rewrites of sections are @emph{very welcome}.

Jan-@AA{}ke Larsson

@end ifnottex

@menu
* Introduction::                Introduction
* Installation::                How to compile and install dvipng
* Basic usage::                 First things first
* Command-line options::        Advanced usage
* Graphics::                    Including PostScript and/or bitmaps
* Color::                       Using color with dvipng
* Diagnosing problems::         Problems?
* Credits::                     People who have contributed
* Copying::                     GNU General Public License
* Index::                       General index
@end menu



@node Introduction
@chapter Introduction

@c man begin DESCRIPTION
@include readme.texi
@c man end

@node Installation
@chapter Installation

@cindex configuration, of dvipng
@cindex compilation
@cindex installation, of dvipng

@include install.texi

@node Basic usage
@chapter Basic usage of dvipng

@cindex invoking dvipng

To use dvipng at its simplest, simply type

@example
dvipng foo
@end example

@noindent
where @file{foo.dvi} is the output of @TeX{} that you want to convert to
PNG format. If there are four pages in @file{foo.dvi}, those pages will
be output as @file{foo1.png}, @file{foo2.png}, @file{foo3.png}, and
@file{foo4.png}, respectively.

If you have enabled the PostScript font support (via FreeType or T1lib),
fonts will be rendered as they are needed. Otherwise, if you use fonts
that have not been used on your system before, they may be automatically
generated; this process can take a few minutes, so progress reports
appear by default. The next time the same font is used, it will have
been saved on disk, so rendering will go much faster. (If dvipng tries
to endlessly generate the same fonts over and over again, something is
wrong. @xref{Unable to generate fonts,,, kpathsea, Kpathsea}.)

Many options are available (see the next section).  For a brief summary
of available options, just type

@example
dvipng --help
@end example

@node Command-line options
@chapter Command-line options

@cindex command-line options
@cindex options, dvipng

dvipng has a plethora of command line options.  Reading through this
section will give a good idea of the capabilities of the driver.

@menu
* Option summary::              Quick listing, from dvipng --help.
* Option details::              More information about each option.
@end menu


@node Option summary
@section Option summary

@cindex options, summary
Here is a handy summary of the options; it is printed out when you run
dvipng with no arguments or with the standard @samp{--help} option.

@example
@include dvipng.help
@end example


@node Option details
@section Option details

@cindex option, details of
@c man begin OPTIONS

Many of the parameterless options listed here can be turned off by
suffixing the option with a zero (@samp{0}); for instance, to turn off
page reversal, use @samp{-r0}.  Such options are marked with a trailing
@samp{*}.

@table @samp
@item -
@cindex options, reading from standard input
@cindex standard input, reading options from
Read additional options from standard input after processing the command
line.

@item --help
Print a usage message and exit.

@item --version
Print the version number and exit.

@item -bd @var{num}
@item -bd @var{color_spec}
@item -bd '@var{num} @var{color_spec}'
@cindex transparent border width
@cindex transparent border fallback color
Set the pixel width of the transparent border (default 0). Using this
option will make the image edges transparent, but it only affects pixels
with the background color. Giving a @var{color_spec} will set the
fallback color, to be used in viewers that cannot handle transparency
(the default is the background color). The color spec should be in
@TeX{} color \special syntax, e.g., 'rgb 1.0 0.0 0.0'. Setting the
fallback color makes the default border width 1 px. @xref{Color}.

@item --bdpi @var{num}
@cindex base resolution, setting
Set the base (Metafont) resolution, both horizontal and vertical, to
@var{num} dpi (dots per inch). This option is necessary when manually
selecting Metafont mode with the --mode option (see below).

@item -bg @var{color_spec}
@cindex background color (option)
Choose background color for the images. This option will be ignored if
there is a background color \special in the DVI. The color spec should
be in @TeX{} color \special syntax, e.g., 'rgb 1.0 0.0 0.0'. You can
also specify 'Transparent' or 'transparent' which will give you a
transparent background with the normal background as a fallback color. A
capitalized 'Transparent' will give a full-alpha transparency, while an
all-lowercase 'transparent' will give a simple fully transparent
background with non-transparent antialiased pixels. The latter would be
suitable for viewers who cannot cope with a true alpha channel.  GIF
images do not support full alpha transparency, so in case of GIF output,
both variants will use the latter behaviour.  @xref{Color}.

@item -d @var{num}
@cindex debugging
Set the debug flags, showing what dvipng (thinks it) is doing. This will
work unless dvipng has been compiled without the @code{DEBUG} option
(not recommended). Set the flags as you need them, use @samp{-d -1} as
the first option for maximum output. @xref{Debug options}. 

@item -D @var{num}
@cindex output resolution, setting
Set the output resolution, both horizontal and vertical, to @var{num}
dpi (dots per inch). 

One may want to adjust this to fit a certain text font size (e.g., on
a web page), and for a text font height of @var{font_px} pixels (in
Mozilla) the correct formula is
@example
@var{dpi} = @var{font_px} * 72.27 / 10 [px * @TeX{}pt/in / @TeX{}pt]
@end example
The last division by ten is due to the standard font height 10pt in
your document, if you use 12pt, divide by 12. Unfortunately, some
proprietary browsers have font height in pt (points), not pixels. You
have to rescale that to pixels, using the screen resolution (default
is usually 96 dpi) which means the formula is
@example
@var{font_px} = @var{font_pt} * 96 / 72 [pt * px/in / (pt/in)] 
@end example
On some high-res screens, the value is instead 120 dpi. Good luck!

@item --depth*
@cindex baseline reporting
@cindex depth reporting
Report the depth of the image. This only works reliably when the
@LaTeX{} style @file{preview.sty} from @previewlatex{} is used. It
reports the number of pixels from the bottom of the image to the
baseline of the image. This can be used for vertical positioning of the
image in, e.g., web documents, where one would use (Cascading
StyleSheets 1)
@example
<IMG SRC="@var{filename.png}" STYLE="vertical-align: -@var{depth}px">
@end example
The depth is a negative offset in this case, so the minus sign is
necessary, and the unit is pixels (px).

@item --dvinum*
Set this option to make the output page number be the @TeX{} page
numbers rather than the physical page number. See the @samp{-o} switch.

@ignore
@item -e @var{num}
@cindex maxdrift
@cindex accuracy in positioning
@cindex positioning accuracy
Maximum drift in pixels of each character from its `true'
resolution-independent position on the page. The default value of this
parameter is resolution dependent (it is the number of entries in the
list [100, 200, 300, 400, 500, 600, 800, 1000, 1200, 1600, 2000, 2400,
2800, 3200, @dots{}] that are less than or equal to the resolution in
dots per inch). Allowing individual characters to `drift' from their
correctly rounded positions by a few pixels, while regaining the true
position at the beginning of each new word, improves the spacing of
letters in words.

@item -f*
@cindex filter, running as a
@cindex standard I/O
@cindex pipes, not readable
@vindex PRINTER@r{, avoided with @samp{-f}}
Run as a filter.  Read the DVI file from standard input and write the
PostScript to standard output.  The standard input must be seekable, so
it cannot be a pipe.  If your input must be a pipe, write a shell script
that copies the pipe output to a temporary file and then points dvipng at
this file.  This option also disables the automatic reading of the
@code{PRINTER} environment variable; use @samp{-P$PRINTER} after the
@samp{-f} to read it anyway.  It also turns off the automatic sending of
control-D if it was turned on with the @samp{-F} option or in the
configuration file; use @samp{-F} after the @samp{-f} to send it anyway.

@item -k*
@cindex cropmarks
Print crop marks.  This option increases the paper size (which should be
specified, either with a paper size special or with the @samp{-T}
option) by a half inch in each dimension.  It translates each page by a
quarter inch and draws cross-style crop marks.  It is mostly useful with
typesetters that can set the page size automatically.  This works by
downloading @file{crop.pro}.
@end ignore

@item -fg @var{color_spec}
@cindex foreground color (option)
Choose foreground color for the images. This option will be ignored if
there is a foreground color \special in the DVI. The color spec should
be in @TeX{} color \special syntax, e.g., 'rgb 1.0 0.0 0.0'.
@xref{Color}.

@item --follow*
@cindex follow mode
Wait for data at end-of-file. One of the benefits of dvipng is that it
does not read the postamble, so it can be started before @TeX{}
finishes. This switch makes dvipng wait at end-of-file for further
output, unless it finds the POST marker that indicates the end of the
DVI. This is similar to @samp{tail -f} but for DVI-to-PNG conversion.

@item --freetype*
@cindex FreeType font rendering
Enable/disable FreeType font rendering (default on). This option is
available if the FreeType2 font library was present at compilation time.
If this is the case, dvipng will have direct support for PostScript
Type1 and TrueType fonts internally, rather than using @samp{gsftopk}
for rendering the fonts. If you have PostScript versions of Computer
Modern installed, there will be no need to generate bitmapped variants
on disk of these. Then, you can render images at different (and unusual)
resolutions without cluttering the disk with lots of bitmapped fonts.
Note that if you have both FreeType and T1lib on your system, FreeType
will be preferred by dvipng. If you for some reason would want to use
T1lib rendering, use this option.

@item --gamma @var{num}
@cindex gamma
@cindex dark fonts
@cindex light fonts
@cindex fuzzy images
Control the interpolation of colors in the greyscale anti-aliasing
color palette.  Default value is 1.0.  For 0 < @var{num} < 1, the
fonts will be lighter (more like the background), and for @var{num} >
1, the fonts will be darker (more like the foreground).

@item --gif*
@cindex GIF image format
The images are output in the GIF format, if GIF support is enabled.
This is the default for the @samp{dvigif} binary, which only will be
available when GIF support is enabled. GIF images are palette images
(see the @samp{--palette} option) and does not support true alpha
channels (see the @samp{--bg} option). See also the @samp{--png}
option.

@item --height*
@cindex baseline reporting
@cindex height reporting
Report the height of the image. This only works reliably when the
@LaTeX{} style @file{preview.sty} from @previewlatex{} is used. It
reports the number of pixels from the top of the image to the
baseline of the image. The total height of the image is obtained as the
sum of the values reported from @samp{--height} and @samp{--depth}.

@item -l [=]@var{num}
@cindex last page printed
@cindex page, last printed
@cindex physical page number, and @samp{-l}
@cindex absolute page number, and @samp{-l}
The last page printed will be the first one numbered @var{num}. Default
is the last page in the document.  If @var{num} is prefixed by an equals
sign, then it (and the argument to the @samp{-p} option, if specified)
is treated as a physical (absolute) page number, rather than a value to
compare with the @TeX{} @samp{\count0} values stored in the DVI file.
Thus, using @samp{-l =9} will end with the ninth page of the document,
no matter what the pages are actually numbered.

@item --mode @var{mode}
@cindex mode name, specifying
@cindex Metafont mode, specifying
Use @var{mode} as the Metafont device name for the PK fonts (both for
path searching and font generation). This needs to be augmented with the
base device resolution, given with the @samp{--bdpi} option. See the
file @url{ftp://ftp.tug.org/tex/modes.mf} for a list of resolutions and
mode names for most devices. @xref{Unable to generate fonts,,, kpathsea,
Kpathsea}.

@item -M*
@cindex font generation, avoiding
@pindex mktexpk@r{, avoiding}
@c this description repeated in kpathsea.texi
Turns off automatic PK font generation (@file{mktexpk}). This will have
no effect when using PostScript fonts, since no PK font generation will
be done anyway.
@ignore
@flindex missfont.log
If @code{mktexpk}, the invocation is appended to a file
@file{missfont.log} (by default) in the current directory. You can then
execute the log file to create the missing files after fixing the
problem.
@vindex TEXMFOUTPUT
@vindex MISSFONT_LOG
If the current directory is not writable and the environment variable or
configuration file value @samp{TEXMFOUTPUT} is set, its value is used.
Otherwise, nothing is written.  The name @samp{missfont.log} is
overridden by the @samp{MISSFONT_LOG} environment variable or
configuration file value.
@end ignore

@item --noghostscript*
@cindex GhostScript, turning off
This switch prohibits the internal call to GhostScript for displaying
PostScript specials. @samp{--noghostscript0} turns the call back on.

@item --nogssafer*
@cindex GhostScript and -dSAFER
@cindex -dSAFER
Normally, if GhostScript is used to render PostScript specials, the
GhostScript interpreter is run with the option @samp{-dSAFER}. The
@samp{--nogssafer} option runs GhostScript without @samp{-dSAFER}. The
@samp{-dSAFER} option in Ghostscript disables PostScript operators such
as deletefile, to prevent possibly malicious PostScript programs from
having any effect.

@item -o @var{name}
@cindex output, redirecting
@cindex standard output, output to
Send output to the file @var{name}. A single occurrence of @samp{%d} or
@samp{%01d}, @dots{}, @samp{%09d} will be exchanged for the physical
page number (this can be changed, see the @samp{--dvinum} switch). The
default output filename is @samp{@var{file}%d.png} where the input DVI
file was @samp{@var{file}.dvi}.

@item -O @var{x-offset},@var{y-offset}
@cindex offset pages
Move the origin by @var{x-offset},@var{y-offset}, a comma-separated
pair of dimensions such as @samp{.1in,-.3cm}.
@c (@pxref{papersize special}).  
The origin of the page is shifted from the default position
(of one inch down, one inch to the right from the upper left corner of
the paper) by this amount.  

@item -p [=]@var{num}
@cindex first page printed
@cindex page, first printed
@cindex physical page number, and @samp{-p}
@cindex absolute page number, and @samp{-p}
The first page printed will be the first one numbered @var{num}. Default
is the first page in the document.  If @var{num} is prefixed by an
equals sign, then it (and the argument to the @samp{-l} option, if
specified) is treated as a physical (absolute) page number, rather than
a value to compare with the @TeX{} @samp{\count0} values stored in the
DVI file.  Thus, using @samp{-p =3} will start with the third page of
the document, no matter what the pages are actually numbered.

@item --palette*
@cindex forcing palette output
Starting from @samp{dvipng} 1.8, the output PNG will be a truecolor
png when an external image is included, to avoid unnecessary delay and
quality reduction, and enable the EPS translator to draw on a
transparent background and outside of the boundingbox. This switch
will force palette (256-color) output and make @samp{dvipng} revert to
the old behaviour, where included images were opaque and always
clipped to the boundingbox. This will also override the
@samp{--truecolor} switch if present.

@item --picky*
@cindex no erroneous images
No images are output when a warning occurs. Normally, dvipng will
output an image in spite of a warning, but there may be something
missing in this image. One reason to use this option would be if you
have a more complete but slower fallback converter. Mainly, this is
useful for failed figure inclusion and unknown \special occurrences,
but warnings will also occur for missing or unknown color specs and
missing PK fonts.

@item --png*
@cindex PNG image format
The images are output in the PNG format. This is the default for the
@samp{dvipng} binary. See also the @samp{--gif} option.

@item -pp @var{firstpage}-@var{lastpage}
@cindex page range
Print pages @var{firstpage} through @var{lastpage}; but not quite
equivalent to @samp{-p @var{firstpage} -l @var{lastpage}}. For example,
when rendering a book, there may be several instances of a page in the
DVI file (one in @code{\frontmatter}, one in @code{\mainmatter}, and one
in @code{\backmatter}). In case of several pages matching, @samp{-pp
@var{firstpage}-@var{lastpage}} will render @emph{all} pages that
matches the specified range, while @samp{-p @var{firstpage} -l
@var{lastpage}} will render the pages from the @emph{first} occurrence
of @var{firstpage} to the @emph{first} occurrence of @var{lastpage}.
This is the (undocumented) behaviour of dvips. In dvipng you can give
both kinds of options, in which case you get all pages that matches the
range in @samp{-pp} between the pages from @samp{-p} to @samp{-l}. Also
multiple @samp{-pp} options accumulate, unlike @samp{-p} and @samp{-l}.
The @samp{-} separator can also be @samp{:}. Note that @samp{-pp -1}
will be interpreted as "all pages up to and including 1", if you want a
page numbered -1 (only the table of contents, say) put @samp{-pp -1--1},
or more readable, @samp{-pp -1:-1}.

@item -q*
@cindex quiet operation
@cindex silent operation
@cindex warnings, suppressing
Run quietly.  Don't chatter about pages converted, etc.@: to standard
output; report no warnings (only errors) to standard error.

@item -Q @var{num}
@cindex antialiasing levels@r{, number of}
@cindex quality
Set the quality to @var{num}. That is, choose the number of antialiasing
levels for PK and T1lib rendering to be @var{num}*@var{num}+1. The default
value is 4 which gives 17 levels of antialiasing for antialiased fonts
from these two. If FreeType is available, its rendering is unaffected by
this option.

@item -r*
@cindex reverse pagination
Toggle output of pages in reverse/forward order. By default, the first
page in the DVI is output first.

@ignore
@item -R
@cindex security
@cindex shell command execution, disabling
@cindex absolute filenames, disabling
@cindex pipes, disabling output to
Run securely.  This disables shell command execution in @code{\special}
(via @samp{`}, @pxref{Dynamic creation of graphics}) and config files
(via the @samp{E} option, @pxref{Configuration file commands}), pipes as
output files, and opening of any absolute filenames.

@item -t @var{papertype}
@cindex paper type
@cindex media
@cindex letter papertype
@cindex legal papertype
@cindex ledger papertype
@cindex a4 papertype
@cindex a3 papertype
@cindex landscape papertype
Set the paper type to @var{papertype}.
@c usually defined in one of the
@c configuration files, along with the appropriate PostScript code to
@c select it (@pxref{Config file paper sizes}).  
You can also specify a @var{papertype} of @samp{landscape}, which
rotates a document by 90 degrees. To rotate a document whose paper type
is not the default, you can use the @samp{-t} option twice, once for the
paper type, and once for @samp{landscape}.
@end ignore

@item --strict*
@cindex exit on erroneous images
The program exits when a warning occurs. Normally, dvipng will output
an image in spite of a warning, but there may be something missing in
this image. One reason to use this option would be if you have a more
complete but slower fallback converter. See the @samp{--picky} option
above for a list of when warnings occur.

@item -T @var{image_size}
Set the image size to @var{image_size} which can be either of
@samp{bbox}, @samp{tight}, or a comma-separated pair of dimensions
@var{hsize},@var{vsize} such as @samp{.1in,.3cm}. The default is
@samp{bbox} which produces a PNG that includes all ink put on the page
and in addition the DVI origin, located 1in from the top and 1in from
the left edge of the paper. This usually gives whitespace above and to
the left in the produced image. The value @samp{tight} will make dvipng
only include all ink put on the page, producing neat images.
@c (@pxref{papersize special}).  
@c This option overrides any papersize special in the DVI file.

@item --t1lib*
@cindex T1lib font rendering
Enable/disable T1lib font rendering (default on). This option is
available if the T1lib font library was present at compilation time. If
this is the case, dvipng will have direct support for PostScript Type1
fonts internally, rather than using @samp{gsftopk} for rendering the
fonts. If you have PostScript versions of Computer Modern installed,
there will be no need to generate bitmapped variants on disk of these.
Then, you can render images at different (and unusual) resolutions
without cluttering the disk with lots of bitmapped fonts. Note that if
you have both FreeType and T1lib on your system FreeType will be
preferred by dvipng, and if you for some reason rather want to use
T1lib, give the option @samp{--freetype0} (see above).

@item --truecolor*
@cindex truecolor output
This will make @samp{dvipng} generate truecolor output. Note that
truecolor output is automatic if you include an external image in your
DVI, e.g., via a PostScript special (i.e., the @samp{graphics} or
@samp{graphicx} package). This switch is overridden by the
@samp{--palette} switch.
 
@item -v* 
Enable verbose operation. This will currently indicate what fonts is
used, in addition to the usual output.

@item -x @var{num}
@cindex magnification, overriding DVI
Set the @math{x} magnification ratio to @math{@var{num}/1000}. Overrides
the magnification specified in the DVI file.  Must be between 10 and
100000.  It is recommended that you use standard magstep values (1095,
1200, 1440, 1728, 2074, 2488, 2986, and so on) to help reduce the total
number of PK files generated.  @var{num} may be a real number, not an
integer, for increased precision.

@item -z @var{num}
@cindex compression
Set the PNG compression level to @var{num}. This option is enabled if
your @samp{libgd} is new enough. The default compression level is 1,
which selects maximum speed at the price of slightly larger PNGs. For an
older @samp{libgd}, the hard-soldered value 5 is used. The include file
@samp{png.h} says
@ifclear man
@quotation
Currently, valid values range from 0 - 9, corresponding directly to the
zlib compression levels 0 - 9 (0 - no compression, 9 - "maximal"
compression). Note that tests have shown that zlib compression levels
3-6 usually perform as well as level 9 for PNG images, and do
considerably fewer calculations. In the future, these values may not
correspond directly to the zlib compression levels.
@end quotation
@end ifclear
@ifset man
``Currently, valid values range from 0 - 9, corresponding directly to
the zlib compression levels 0 - 9 (0 - no compression, 9 - "maximal"
compression). Note that tests have shown that zlib compression levels
3-6 usually perform as well as level 9 for PNG images, and do
considerably fewer calculations. In the future, these values may not
correspond directly to the zlib compression levels.''
@end ifset
@end table
@c man end

@ignore
@c @node Environment variables
@chapter Environment variables

@cindex environment variables

dvipng looks for many environment variables, to define search paths and
other things.  The path variables are read as needed, after all
configuration files are read, so they override values in the
configuration files.  (Except for @code{TEXCONFIG}, which defines where
the configuration files themselves are found.)

@xref{Path specifications,,, kpathsea, Kpathsea}, for details of
interpretation of path and other environment variables common to all
Kpathsea-using programs.  Only the environment variables specific to
dvipng are mentioned here.

@vtable @code
@item DVIPSMAKEPK
@pindex mktexpk@r{, changing name}
Overrides @samp{mktexpk} as the name of the program to invoke to
create missing PK fonts.  You can change the arguments passed to the
@code{mktexpk} program with the @code{MAKETEXPK} environment
variable; @pxref{MakeTeX script arguments,,, kpathsea, Kpathsea}.

@item DVIPSRC
Specifies the name of the startup file (@pxref{Configuration file
searching}) which is read after @file{config.ps} but before any
printer-specific configuration files.

@item TEXPICTS
Path to search for included graphics files.  Overrides the @samp{S}
config file option (@pxref{Configuration file commands}).  If not set,
@code{TEXINPUTS} is looked for.  @xref{Supported file formats,,,
kpathsea, Kpathsea}.

@end vtable

@c @node Paper size and landscape
@chapter Paper size and landscape orientation

@cindex paper size, general

Most @TeX{} documents at a particular site are designed to use the
standard paper size (letter size in the United States, A4 in Europe).
The dvipng program can be customized either sitewide or for a particular
printer.

@cindex landscape orientation, defined
But many documents are designed for other paper sizes.  For instance,
you may want to design a document that has the long edge of the paper
horizontal.  This can be useful when typesetting booklets, brochures,
complex tables, or many other documents.  This type of paper orientation
is called @dfn{landscape} orientation (the default orientation is
@dfn{portrait}).  Alternatively, a document might be designed for ledger
or A3 paper.

Since the intended paper size is a document design decision, not a
printing decision, such information should be given in the @TeX{} file
and not on the dvipng command line. For this reason, dvipng supports a
@samp{papersize} special. It is hoped that this special will become
standard over time for @TeX{} previewers, printer drivers, and other DVI
drivers.

@menu
* papersize special::           Specifying the paper size in TeX.
* Config file paper sizes::     Specifying printer- and site-specific sizes.
@end menu


@c @node papersize special
@section @samp{papersize} special

@findex papersize @r{special}

The format of the @samp{papersize} special is

@example
\special@{papersize=@var{width},@var{height}@}
@end example

@noindent
@var{width} is the horizontal size of the page, and @var{height} is the
vertical size.  The dimensions supported are the same as for @TeX{};
namely, in (inches), cm (centimeters), mm (millimeters), pt (points), sp
(scaled points), bp (big points, the same as the default PostScript
unit), pc (picas), dd (didot points), and cc (ciceros).

@findex landscape@r{, as @code{\special}}
For a US letter size landscape document, the @code{papersize} would be:
@example
\special@{papersize=11in,8.5in@}
@end example

@noindent
An alternate specification of @code{landscape}:
@example
\special@{landscape@}
@end example

@noindent
This is supported for backward compatibility, but it is hoped that
eventually the @code{papersize} comment will dominate.

Of course, such a @code{\special} only informs dvipng of the desired
paper size; you must also adjust @code{\hsize} and @code{\vsize} in your
@TeX{} document typeset to those dimensions.

The @code{papersize} special must occur somewhere on the first page of
the document.


@c @node Config file paper sizes
@section Configuration file paper size command

@cindex paper size configuration file command
@cindex configuration file paper size command

The @samp{@@} command in a configuration file sets the paper size
defaults and options.  The first @samp{@@} command defines the default
paper size.  It has three possible parameters:

@example
@@ @r{[}@var{name} @r{[}@var{hsize} @var{vsize}@r{]]}
@end example

If @samp{@@} is specified on a line by itself, with no parameters, it
instructs dvipng to discard all previous paper size information (possibly
from another configuration file).

If three parameters are given, with the first parameter being a name and
the second and third being a dimension (as in @samp{8.5in} or
@samp{3.2cc}, just like in the @samp{papersize} special), then the
option is interpreted as starting a new paper size description, where
@var{name} is the name and @var{hsize} and @var{vsize} define the
horizontal and vertical size of the sheet of paper, respectively. For
example:

@example
@@ letterSize 8.5in 11in
@end example

If both @var{hsize} and @var{vsize} are zero (you must still specify
units!) then any page size will match.  If the @samp{@@} character is
immediately followed by a @samp{+} sign, then the remainder of the line
(after skipping any leading blanks) is treated as PostScript code to
send to the printer, presumably to select that particular paper size:

@example
@@ letter 8.5in 11in
@@+ %%BeginPaperSize: Letter
@@+ letter
@@+ %%EndPaperSize
@end example

After all that, if the first character of the line is an exclamation
point, then the line is put in the initial comments section of the final
output file; else, it is put in the setup section of the output file.
For example:

@example
@@ legal 8.5in 14in
@@+ ! %%DocumentPaperSizes: Legal
@@+ %%BeginPaperSize: Legal
@@+ legal
@@+ %%EndPaperSize
@end example

When dvipng has a paper format name given on the command line, it looks
for a match by the @var{name}; when it has a @samp{papersize} special,
it looks for a match by dimensions.  The first match found (in the order
the paper size information is found in the configuration file) is used.
If nothing matches, a warning is printed and the first paper size is
used.  The dimensions must match within a quarter of an inch.  Landscape
mode for all paper sizes is automatically supported.

If your printer has a command to set a special paper size, then give
dimensions of @samp{0in 0in}; the PostScript code that sets the paper
size can refer to the dimensions the user requested as @samp{hsize} and
@samp{vsize}; these will be macros defined in the PostScript that return
the requested size in default PostScript units.  Virtually all of the
PostScript commands you use here are device-dependent and degrade the
portability of the file; that is why the default first paper size entry
should not send any PostScript commands down (although a structured
comment or two would be okay).  Also, some printers want
@samp{BeginPaperSize} comments and paper size setting commands; others
(such as the NeXT) want @samp{PaperSize} comments and they will handle
setting the paper size.  There is no solution I could find that works
for both (except maybe specifying both).

@flindex mkdvipngpapers
The Perl 5 script @file{contrib/mkdvipngpapers} in the distribution
directory may help in determining appropriate paper size definitions.

@cindex a4 paper size, as default
If your printers are configured to use A4 paper by default, the
configuration file (probably the global @file{config.ps} in this case)
should include this as the first @samp{@@} command:

@example
@@ A4size 210mm 297mm
@@+ %%PaperSize: A4
@end example

@noindent
so that @code{A4size} is used as the default, and not @code{A4} itself;
thus, no PostScript @code{a4} command is added to the output file,
unless the user explicitly says to use paper size @samp{a4}.  That is,
by default, no paper size PostScript command should be put in the
output, but dvipng will still know that the paper size is A4 because
@samp{A4size} is the first (and therefore default) size in the
configuration file.

Executing the @samp{letter} or @samp{a4} or other PostScript operators
cause the document to be nonconforming and can cause it not to print on
certain printers, so the default paper size should not execute such an
operator if at all possible.



@c @node Interaction with PostScript
@chapter Interaction with PostScript

@cindex interaction with PostScript
@cindex PostScript interaction

dvipng supports inclusion of PostScript figure files (e.g., Encapsulated
PostScript), downloading other header files (e.g., fonts), including
literal PostScript code, and hypertext.

@menu
* PostScript figures::          Including an Encapsulated PostScript figure.
* Header files::                Downloading extra definitions.
* Diagnosing problems::         
@end menu


@c @node PostScript figures
@chapter PostScript figures

Scaling and including PostScript graphics is a breeze---if the PostScript
file is correctly formed.  Even if it is not, however, the file can usually
be accommodated with just a little more work.

@menu
* Bounding box::                The %%BoundingBox EPS comment.
* EPSF macros::                 Including the file in TeX.
* psfile special::              The basic special.
* Dynamic creation of graphics::  Handling compressed or generated figures.
* Fonts in figures::            The %*Font comment.
@end menu


@c @node Bounding box
@section The bounding box comment

@cindex bounding box, comment for

The most important feature of a good PostScript file from the standpoint
of including it in another document is an accurate bounding box comment.
Every well-formed PostScript file has a comment describing where on the
page the graphic is located, and how big that graphic is.

@cindex big points
@cindex PostScript units
@cindex bounding box, defined
This information is given as the lower left and upper right corners of
the box just enclosing the graphic, and is thus referred to as the
@dfn{bounding box}.  These coordinates are given in the default
PostScript units (there are precisely 72 PostScript units to the inch,
like @TeX{} big points) with respect to the lower left corner of the
sheet of paper.

@findex %%BoundingBox
To see if a PostScript file has a bounding box comment, just look at the
first few lines of the file.  PostScript files are standard ASCII, so
you can use any text editor to do this.  If within the first few dozen
lines there is a line like

@example
%%BoundingBox: 25 50 400 300
@end example

@noindent
(with any reasonable numbers), chances are very good that the file is
Encapsulated PostScript and will work easily with dvipng.  If the file
contains instead a line like

@findex atend@r{, bounding box specification}
@findex (atend)@r{, bounding box specification}
@example
%%BoundingBox: (atend)
@end example

@noindent
the file is still probably Encapsulated PostScript, but the bounding box
is given at the end of the file.  dvipng needs it at the beginning.  You
can move it with that same text editor, or a simple script.  (The
bounding box is given in this way when the program that generated the
PostScript couldn't know the size in advance, or was too lazy to compute
it.)

@pindex bbfig
@cindex bounding box, determining
If the document lacks a @samp{%%BoundingBox:} altogether, you can
determine one in a couple of ways.  One is to use the @samp{bbfig}
program distributed with dvipng in the @file{contrib} directory. This can
usually find the correct bounding box automatically; it works best with
Ghostscript.

@vindex 612 792 @r{bounding box size}
If the comment looks like this:
@example
%%BoundingBox: 0 0 612 792
@end example

@noindent
the graphic claims to take up an entire sheet of paper.  This is
usually a symptom of a bug in the program that generated it.

The other is to do it yourself: print the file.  Now, take a ruler, and
make the following measurements (in PostScript units, so measure in
inches and multiply by 72): From the left edge of the paper to the
leftmost mark on the paper is @var{llx}, the first number.  From the
bottom edge of the paper to the bottommost mark on the paper is
@var{lly}, the second number.  From the left edge of the paper to the
rightmost mark on the paper is @var{urx}, the third number.  The fourth
and final number, @var{ury}, is the distance from the bottom of the page
to the uppermost mark on the paper.

Once you have the numbers, add a comment of the following form as the
second line of the document.  (The first line should already be a line
starting with the two characters @samp{%!}; if it is not, the file
probably isn't PostScript.)

@example
%%BoundingBox: @var{llx} @var{lly} @var{urx} @var{ury}
@end example

@noindent
Or, if you don't want to modify the file, you can simply write these
numbers down in a convenient place and give them in your @TeX{} document
when you import the graphic, as described in the next section.

If the document does not have such a bounding box, or if the bounding
box is given at the end of the document, or the bounding box is wrong,
please complain to the authors of the software package that generated
the file.


@c @node EPSF macros
@section Using the EPSF macros

@cindex EPSF macros
@cindex macros for epsf inclusion

Once the figure file has a bounding box comment (see the previous
section,) you are ready it the graphic into a @TeX{} document.  Many
packages for using EPS files exist.  One distributed with dvipng is the
files @file{epsf.tex} (for plain @TeX{}) and @file{epsf.sty} (for
La@TeX{}).  For plain @TeX{}, add a line like this near the top of your
input file:

@flindex epsf.tex
@example
\input epsf
@end example

@noindent
If you are using La@TeX{} 2e, use the @samp{graphics} or @samp{graphicx}
package.  
@flindex epsf.sty
If you are using La@TeX{} 2.09, add the @samp{epsf} style option, as in:

@example
\documentstyle[12pt,epsf]@{article@}
@end example

@noindent
In any case, the above only needs to be done once, no matter how many
figures you plan to include.

Now, at the point you want to include a file, enter a line such as:

@example
\epsffile@{foo.eps@}
@end example

@findex \leavevmode
@cindex bounding box, supplying to @TeX{}
If you are using La@TeX{}, you may need to add @code{\leavevmode}
immediately before the @code{\epsffile} command to get certain
environments to work correctly.  If your file does not have a bounding
box comment, you can supply the numbers as determined in the previous
section, in the same order they would have been in a normal bounding box
comment:

@example
\epsffile[100 100 500 500]@{foo.ps@}
@end example

@noindent
Now, save your changes and run @TeX{} and dvipng; the output should have
your graphic positioned at precisely the point you indicated, occupying
the proper amount of space.

@findex \epsffile @r{macro}
@cindex figures, natural size
The @code{\epsffile} macro typesets the figure as a @TeX{} @code{\vbox}
at the point of the page that the command is executed.  By default, the
graphic will have its `natural' width (namely, the width of its bounding
box).  The @TeX{} box will have depth zero and its natural height.  By
default, the graphic will be scaled by any DVI magnification in effect,
just as is everything else in your document.  See the next section for
more information on scaling.

@vindex \epsfverbosetrue
@cindex verbose EPSF processing
If you want @TeX{} to report the size of the figure as a message on your
terminal when it processes each figure, give the command:

@example
\epsfverbosetrue
@end example

@menu
* EPSF scaling::                
* EPSF clipping::               
@end menu


@c @node EPSF scaling
@subsection EPSF scaling

@cindex scaling of figures
@cindex figures, scaling

Usually, you will want to scale an EPSF figure to some size appropriate
for your document, since its natural size is determined by the creator
of the EPS file.

The best way to do this is to assign the desired size to the @TeX{}
@code{\epsfxsize} or @code{\epsfysize} variables, whichever is more
convenient for you.  That is, put

@vindex \epsfxsize
@example
\epsfxsize=@var{dimen}
@end example

@noindent
right before the call to @code{\epsffile}.  Then the width of the @TeX{}
box will be @var{dimen} and its height will be scaled proportionately.
Similarly, you can set the vertical size with

@vindex \epsfysize
@example
\epsfysize=@var{dimen}
@end example

@noindent
in which case the height will be set and the width scaled
proportionally.

If you set both, both will be honored, but the aspect ratio of the
included graphic may necessarily be distorted, i.e., its contents
stretched in one direction or the other.

@findex \epsfsize
You can resize graphics in a more general way by redefining the
@code{\epsfsize} macro.  @code{\epsffile} calls this with two
parameters: the natural horizontal and vertical sizes of the PostScript
graphic.  @code{\epsfsize} must expand to the desired horizontal size,
that is, the width of the @code{\vbox}.  Schematically:

@example
\def\epsfsize#1#2@{@var{body}@}
@end example

Some useful definitions of @var{body}:

@table @samp
@item \epsfxsize
This definition (the default) enables the default features listed above,
by setting @code{\epsfxsize} to the same value it had before the macro
was called.

@item #1
Force the natural size by returning the first parameter (the original
width).

@item 0pt
A special case, equivalent to @samp{#1}.

@item 0.5#1
Scale to half the natural size.

@item \hsize
Scale to the current @code{\hsize}.  (In La@TeX{}, use @code{\textwidth}
instead of @code{\hsize}.)

@item \ifnum#1>\hsize\hsize\else#1\fi
If the natural width is greater than the current @code{\hsize}, scale to
@code{\hsize}, otherwise use the natural width.

@end table

@cindex DVI magnification
@cindex magnification, DVI
@vindex \magnification
For compatibility with other PostScript drivers, it is possible to turn
off the default scaling of included figures by the DVI magnification
with the following @TeX{} command:

@vindex /magscale
@example
\special@{! /magscale false def@}
@end example

@noindent
Use of this command is not recommended because it will make the
@code{\epsffile} graphics the ``wrong'' size if global magnification is
being used, and it will cause any PostScript graphics to appear
improperly scaled and out of position if a DVI to DVI program is used to
scale or otherwise modify the document.

@findex bop-hook
DVI magnification is not applied to any output from code you write in
@samp{bop-hook} or its ilk (@pxref{PostScript hooks}),


@c @node EPSF clipping
@subsection EPSF clipping

@cindex clipping of EPSF
@cindex bounding box, inaccurate
@cindex text in figures, chopped off
@cindex lines in figures, wrong width

By default, clipping is disabled for included EPSF images.  This is
because clipping to the bounding box dimensions often cuts off a
small portion of the figure, due to slightly inaccurate bounding
box arguments.  The problem might be subtle; lines around the boundary
of the image might be half their intended width, or the tops or
bottoms of some text annotations might be sliced off.  If you want to
turn clipping on, just use the command

@example
\epsfclipon
@end example

@noindent
and to turn clipping back off, use

@example
\epsfclipoff
@end example


@c @node psfile special
@section @samp{psfile} special

@findex psfile @r{special}

The basic special for file inclusion is as follows:

@example
\special@{psfile=@var{filename}.ps @r{[}@var{key}=@var{value}@r{]} @dots{} @}
@end example

@noindent
This downloads the PostScript file @file{@var{filename}.ps} such that
the current point will be the origin of the PostScript coordinate
system.  The optional @var{key}@t{=}@var{value} assignments allow you to
specify transformations on the PostScript.

The possible @var{key}s are:

@table @samp

@item hoffset
The horizontal offset (default 0)
@item voffset
The vertical offset (default 0)
@item hsize     
The horizontal clipping size (default 612)
@item vsize     
The vertical clipping size (default 792)
@item hscale    
The horizontal scaling factor (default 100)
@item vscale    
The vertical scaling factor (default 100)
@item angle     
The rotation (default 0)
@item clip    
Enable clipping to the bounding box
@end table

The dimension parameters are all given in PostScript units.
The @samp{hscale} and @samp{vscale} are given in non-dimensioned percentage
units, and the rotation value is specified in degrees.
Thus

@example
\special@{psfile=foo.ps hoffset=72 hscale=90 vscale=90@}
@end example

@noindent
will shift the graphics produced by file @file{foo.ps} right by one inch
and will draw it at 0.9 times normal size.  Offsets are given relative
to the point of the special command, and are unaffected by scaling or
rotation.  Rotation is counterclockwise about the origin.  The order of
operations is to rotate the figure, scale it, then offset it.

For compatibility with older PostScript drivers, it is possible to change
the units that @samp{hscale} and @samp{vscale} are given in.  This can be
done by redefining @samp{@@scaleunit}
@vindex scaleunit
in @samp{SDict}
@vindex SDict
by a @TeX{} command such as

@example
\special@{! /@@scaleunit 1 def@}
@end example

@noindent
The @samp{@@scaleunit} variable, which is by default 100, is what
@samp{hscale} and @samp{vscale} are divided by to yield an absolute
scale factor.


@c @node Dynamic creation of graphics
@section Dynamic creation of PostScript graphics files

@cindex dynamic creation of graphics
@cindex compressed PostScript
@cindex uncompressing PostScript

PostScript is an excellent page description language---but it does tend
to be rather verbose.  Compressing PostScript graphics files can reduce
them by factor of five or more.  For this reason, if the name of an
included PostScript file ends with @file{.Z} or @file{.gz}, dvipng
automatically runs @samp{gzip -d}.  For example:

@example
\epsffile[72 72 540 720]@{foo.ps.gz@}
@end example

@noindent
Since the results of such a command are not accessible to @TeX{}, if you
use this facility with the @file{epsf} macros, you need to supply the
bounding box parameter yourself, as shown.

More generally, if the filename parameter to one of the graphics
inclusion techniques starts with a left quote (@samp{`}), the parameter
is instead interpreted as a command to execute that will send the actual
file to standard output.  For example:

@example
\special@{psfile="`gnuplot foo"@}
@end example

@noindent
@flindex gnuplot
to include the file @file{foo}.  Of course, the command to be executed
can be anything, including using a file conversion utility such as
@file{tek2ps} or whatever is appropriate.  This feature can be disabled
with the @samp{-R} command-line option or @samp{R} configuration option.


@c @node Fonts in figures
@section Fonts in figures

@cindex figures and fonts
@cindex fonts, in PostScript figures
@findex %*Font

You can use any font available to @TeX{} and dvipng within a graphics
file by putting a @code{%*Font:} line in the leading commentary of the
file.  Schematically, this looks like:

@example
%*Font: @var{tfmname} @var{scaledbp} @var{designbp} @var{hex-start}:@var{hex-bitstring}
@end example

Here is the meaning of each of these elements:

@table @var
@item tfmname
The @TeX{} TFM filename, e.g., @file{cmr10}.  You can give the same
@var{tfmname} on more than one @samp{%*Font} line; this is useful when
the number of characters from the font used needs a longer
@var{hex-bitstring} (see item below) than conveniently fits on one line.

@item scaledbp
The size at which you are using the font, in PostScript points (@TeX{}
big points).  72@dmn{bp} = 72.27@dmn{pt} = 1@dmn{in}.

@item designbp
The designsize of the font, again in PostScript points.  This should
match the value in the TFM file @var{tfmname}.  Thus, for @file{cmr10},
it should be @samp{9.96265}.

@item hex-start
The character code of the first character used from the font, specified
as two ASCII hexadecimal characters, e.g., @samp{4b} or @samp{4B} for
@samp{K}.

@item hex-bitstring
An arbitrary number of ASCII hexadecimal digits specifying which
characters following (and including) @var{hex-start} are used.  This is
treated as a bitmap.  For example, if your figure used the single letter
@samp{K}, you would use @samp{4b:8} for @var{hex-start} and
@var{hex-bitstring}.  If it used @samp{KLMNP}, you would use
@samp{4b:f4}.

@end table

MetaPost's output figures contain lines like this for bitmap fonts used
in a MetaPost label (@pxref{MetaPost,,, web2c, Web2c}).


@c @node Header files
@chapter PostScript header files

@cindex header files, defined
@cindex PostScript header files

@dfn{Header files} are bits of PostScript included in the output file;
generally they provide support for special features, rather than
producing any printed output themselves.  You can explicitly request
downloading header files if necessary for some figure, or to achieve
some special effect.

@vindex psheaderdir
@flindex .pro @r{prologue files}
@flindex .lpro @r{long prologue files}
dvipng includes some headers on its own initiative, to implement features
such as PostScript font reencoding, bitmap font downloading, handling of
@code{\special}'s, and so on.  These standard headers are the
@file{.pro} files (for ``prologue'') in the installation directory
@samp{$(psheaderdir)}; they are created from the @file{.lpro} (``long
prologue'') files in the distribution by stripping
comments, squeezing blank lines, etc., for maximum efficiency.  If you
want to peruse one of the standard header files, read the @file{.lpro}
version.

@vindex userdict@r{, and dictionary files}
@cindex dictionary, @code{userdict}
The PostScript dictionary stack will be at the @samp{userdict} level
when header files are included.

@end ignore

@node Graphics
@chapter Graphics 

@samp{dvipng} attempts to handle graphics as included by the
@samp{graphicx} and @samp{graphics} packages, without the need of
specifying a driver to these packages. This means that it recognizes
the encapsulated postscript inclusion meant for @samp{dvips}, but is
also able (from version 1.8) to include bitmapped graphics, see the
details below.

@menu
* Encapsulated PostScript::    An internal call to GhostScript
* Bitmapped graphics::         PNG, JPEG and GIF
@end menu

@node Encapsulated PostScript
@section Encapsulated PostScript

When an EPS file is included, a call to GhostScript is performed to
produce a bitmapped image that can be included. The default is to
produce an image with transparent background, at the same size as the
DVI page currently being converted to PNG, and include that as
foreground on the PNG. Of course, if the image is to be cropped, that
is done. The included image will be a truecolor image, so for maximum
performance the output PNG will be in truecolor mode as well.

This conversion needs the @samp{pngalpha} output device to be present
in your copy of GhostScript. If that device is not present, or you use
the @samp{--palette} switch or request GIF output, the fallback is to
use the @samp{png16m} device to produce a cropped opaque image for
inclusion. Other relevant switches are @samp{--noghostscript} and
@samp{--nogssafer}. @xref{Option details}.

@cindex PostScript inclusion problems
The most common problem with including graphics is an incorrect
bounding box. Complain to whoever wrote the software that generated
the file if the bounding box is indeed incorrect. An adjusted
boundingbox can be specified in the @samp{\includegraphics} call, as
in this example (using @samp{graphicx}):

@example
\includegraphics[bb=10 20 100 200]@{imagename.eps@}
@end example


@node Bitmapped graphics
@section Bitmapped graphics

dvipng can include PNG, JPEG and GIF graphics. When including such
images via @samp{\includegraphics} you need to specify the bounding
box since @TeX{} itself cannot read them from the files in question.
The bounding box size should be given as @samp{0 0 w h} in pixels,
e.g., if the file @samp{imagename.png} is 300x400 pixels, the
inclusion would read

@example
\includegraphics[bb=0 0 300 400]@{imagename.png@}
@end example

The default size is the image size in bp (``big points'' in TeX
nomenclature or PostScript points as other people have it, 72 per inch).
That is, default resolution will be 72 dpi for included bitmaps, which
is the default size in the few other bitmap-capable drivers that are
known to me (dvipdfm and PDFLaTeX).

If you want 100 dpi you need to specify the width accordingly. You
just divide your image width by 100: a 135 pixel wide image at 100 dpi
will take up 1.35 inches. If you want 200 dpi you divide by 200, and
so on. Simple, eh? The example above at 200 dpi would be 1.5 inches
wide:

@example
\includegraphics[bb=0 0 300 400,witdh=1.5in]@{imagename.png@}
@end example

@node Color
@chapter Color

To support color, dvipng recognizes a certain set of specials. These
specials start with the keyword @samp{color} or the keyword
@samp{background}, followed by a color specification.

@menu
* Color specifications::        
* Color specials::              
@end menu


@node Color specifications
@section Color specifications

@cindex color specifications

The color specification supported by dvipng is by-value or by-name. The
by-value spec starts with the name of a color model (one of @samp{rgb},
@samp{hsb}, @samp{cmy}, @samp{cmyk}, or @samp{gray}) followed by the
appropriate number of parameters. Thus, the color specification
@samp{rgb 0.3 0.4 0.5} would correspond to the color that is @samp{0.3
0.4 0.5} in its red, blue and green values. The color model used 
internally in dvipng is @samp{RGB} (discretized to 256 levels), for 
details on the formulas used in conversion, see the @samp{xcolor} 
documentation.

By-name color specifications are single (case-dependent) words and are
compared with color names defined in @samp{dvipsnam.def} (from the
@samp{graphics} bundle), @samp{svgnam.def} and @samp{xcolor.sty} (from
the @samp{xcolor} bundle). See the @samp{xcolor} documentation for a
list of names and the corresponding colors.

On the command-line, the name @samp{Transparent} can also be used as
an argument to @samp{--bg} to choose transparent background.
@xref{Option details}.

@node Color specials
@section Color specials

We will describe @samp{background} first, since it is the simplest. The
@samp{background} keyword must be followed by a color specification.
That color specification is used as a fill color for the background. The
last @samp{background} special on a page is the one that gets used, and
is used for the whole of the page image. (This is possible because the
prescan phase of dvipng notices all of the color specials so that the
appropriate information can be written out during the second phase.)

The @samp{color} special itself has three forms. The first is just
@samp{color} followed by a color specification. In this case, the
current global color is set to that color; the color stack must be empty
when such a command is executed.

The second form is @samp{color push} followed by a color specification.
This saves the current color on the color stack and sets the color to be
that given by the color specification.  This is the most common way to
set a color.

The final form of the @samp{color} special is just @samp{color pop},
with no color specification; this says to pop the color last pushed on
the color stack from the color stack and set the current color to be
that color.

dvipng correctly handles these color specials across pages, even when
the pages are rendered repeatedly or in reverse order.

@node Diagnosing problems
@chapter Diagnosing problems

@cindex problems
@cindex trouble
@cindex debugging

You've gone through all the trouble of installing dvipng, carefully read
all the instructions in this manual, and still can't get something to
work. The following sections provide some helpful hints if you find
yourself in such a situation.

@menu
* Contact information::         Who to ask.
* Debug options::               Getting diagnostics.
@end menu

@node Contact information
@section Contact information

Bug reports should be sent to
@email{dvipng@@nongnu.org}. 

Questions, suggestions for new features, pleas for help, and/or praise
should go to @email{dvipng@@nongnu.org}. For more information on this
mailing list, send a message with just the word `help' as subject or
body to @email{dvipng-request@@nongnu.org} or look at
@url{http://lists.nongnu.org/mailman/listinfo/dvipng}.

Offers to support further development will be appreciated. For developer
access, ask on @email{dvipng@@nongnu.org}.

For details on the @TeX{} path-searching library, and @code{mktexpk}
problems, @pxref{Common problems,,, kpathsea, Kpathsea}.


@node Debug options
@section Debug options

The @samp{-d} flag to dvipng helps in tracking down certain errors.  The
parameter to this flag is an integer that tells what errors are
currently being tracked.  To track a certain class of debug messages,
simply provide the appropriate number given below; if you wish to track
multiple classes, sum the numbers of the classes you wish to track.  To
track all classes, you can use @code{-1}.  

Some of these debugging options are actually provided by Kpathsea
(@pxref{Debugging, , , kpathsea, Kpathsea}).

The classes are:
@table @asis
@item 1 
Normal dvi op-codes
@item 2
Virtual fonts
@item 4
PK fonts
@item 8
TFM files
@item 16
Glyph rendering
@item 32
FreeType calls
@item 64
Encoding loads
@item 128
Color specials
@item 256
GhostScript specials
@item 512
T1lib calls
@item 1024
Kpathsea @code{stat} calls
@item 2048
Kpathsea hash table lookups
@item 4096
Kpathsea path element expansion
@item 8192
Kpathsea path searches
@ignore
@item 16384
@end ignore

@end table

@node Credits
@chapter Credits

A number of persons have contributed, if I forget to mention someone,
I apologize. First and foremost we have David Kastrup whose
@previewlatex{} project provided the incentive to write this program.
There is also a number of people who have contributed by reporting
bugs and suggesting improvements as the thing has evolved. These
include but is perhaps not limited to (in semi-random order): Thomas
Esser (te@TeX{}), Christian Schenk (MIK@TeX{}), Brian R Furry (debian
package), Angus Leeming (LyX), Thomas Boutell (libgd), John Jones
(first user report), Uwe Kern (xcolor), Karl Berry (@TeX{} Live),
David Harvey (hinting in Freetype), Neal Harmon, Alan Shutko, Reiner
Stieb, Nick Alcock, Adam Buchbinder, Svend Tollak Munkejord, James
Longstreet, Bernhard Simon, Bob McElrath, Georg Schwarz, Jason Farmer,
Brian V. Smith, Samuel Hathaway, Thomas R. Shemanske, Stephen Gibson,
Christian Ridderstr@"om, Ezra Peisach, William H Wheeler, Thomas
Klausner, Harald Koenig, Adrian Bunk, Kevin Smith, Jason Riedy,
Wolfram Krause, and Reinhard Kotucha.

@ifset man
@c man begin NOTES
The full manual is accessible in the info format, on most systems by typing
@example
info dvipng
@end example
@c man end
@c man begin COPYRIGHT
This program is released under the GNU General Public License, see the
COPYING file in the dvipng distribution or
@url{http://www.gnu.org/licenses/gpl.html}.

Copyright @copyright{} 2002-2006 Jan-@AA{}ke Larsson
@c man end
@end ifset

@node Copying
@chapter Copying


This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.

@sp 2
@noindent
Copyright @copyright{} 2002-2006 Jan-@AA{}ke Larsson

@node Index
@unnumbered Index

@printindex cp
@bye